Introspect Access Tokens

This guide shows how to configure token introspection for a .NET API using the MonoCloud API Authentication .NET SDK.

With introspection, tokens are validated by sending them to the authorization server's introspection endpoint instead of being validated locally. This is required for opaque tokens and can also be enabled for JWT tokens.

When to use introspection

Use introspection when:

Your API receives opaque access tokens
You want to receive token claims and check revocation status
You want all tokens validated server-side

Before you begin

This guide assumes you've completed the installation guide.

You should already have:

An ASP.NET Core project
The MonoCloud.Authentication.Api SDK installed
The MonoCloud section configured in appsettings.json

Configure the application

Introspection requires a Client ID and a client authentication method. Add the client credentials to your appsettings.json:

appsettings.json

{
  "MonoCloud": {
    "TenantDomain": "https://<your-domain>",
    "Audience": "https://<your-api-audience>",
    "ClientId": "<your-client-id>",
    "ClientSecret": "<your-client-secret>"
  }
}

Where to find these values

Setting	Where to find the value in MonoCloud
`ClientId`	Client ID from your API settings
`ClientSecret`	Client Secret from your API settings

Protect endpoints with introspection

Set ClientId and a ClientAuth method — opaque tokens are then validated through introspection. Setting IntrospectJwtTokens to true ensures that JWT access tokens are also introspected by the authorization server rather than validated locally.

Program.cs

using MonoCloud.Authentication.Api;
using MonoCloud.Authentication.Api.Shared.ClientAuth;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddAuthentication(MonoCloudAuthenticationDefaults.AuthenticationScheme)
    .AddMonoCloudAuthentication(options =>
    {
        options.TenantDomain = builder.Configuration["MonoCloud:TenantDomain"];
        options.Audience = builder.Configuration["MonoCloud:Audience"];
        options.ClientId = builder.Configuration["MonoCloud:ClientId"];
        options.ClientAuth = new ClientSecretAuth(builder.Configuration["MonoCloud:ClientSecret"]!);

        options.IntrospectJwtTokens = true;
    });

builder.Services.AddAuthorization();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/api/data", () => "Protected data")
   .RequireAuthorization();

app.Run();

How it works: