Install and set up the MonoCloud API Authentication .NET SDK

This guide shows how to install the MonoCloud API Authentication .NET SDK and configure your .NET API with MonoCloud.

By the end of this guide, you will have:

Your API configured in the MonoCloud Dashboard
The SDK installed in your ASP.NET Core project
Configuration in place for token validation

If you already have a MonoCloud account and API, skip ahead to Install the SDK.

Create a MonoCloud account

If you don’t have an account yet, sign up at: https://www.monocloud.com

Create an API

In the MonoCloud Dashboard:

Click Add API
Set the Audience (for example https://api.example.com) — this uniquely identifies your API
Add any scopes your API requires (for example read, write)

Each API represents a single resource server secured by MonoCloud.

Install the SDK

Install the MonoCloud API Authentication .NET SDK using the .NET CLI:

Terminal

dotnet add package MonoCloud.Authentication.Api

The SDK supports applications targeting .NET 6.0 or later.

Configure the application

Add a MonoCloud section to your appsettings.json:

appsettings.json

{
  "MonoCloud": {
    "TenantDomain": "https://<your-domain>",
    "Audience": "https://<your-api-audience>"
  }
}

Where to find these values

Setting	Where to find the value in MonoCloud
`TenantDomain`	Domain from your tenant or API settings
`Audience`	Audience from the API settings

Register the authentication handler

Bind the configuration to the MonoCloud authentication scheme in Program.cs:

Program.cs

using MonoCloud.Authentication.Api;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddAuthentication(MonoCloudAuthenticationDefaults.AuthenticationScheme)
    .AddMonoCloudAuthentication(options =>
    {
        options.TenantDomain = builder.Configuration["MonoCloud:TenantDomain"];
        options.Audience = builder.Configuration["MonoCloud:Audience"];
    });

builder.Services.AddAuthorization();

var app = builder.Build();

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

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

app.Run();

AddMonoCloudAuthentication() registers a standard ASP.NET Core authentication handler, so it works with [Authorize], RequireAuthorization(), and the authorization policy system.

Do not hardcode secrets. Load the tenant domain, client id, and client secret from environment variables, user secrets, or a secure secret store.

Options reference

Configure these on MonoCloudAuthenticationOptions inside AddMonoCloudAuthentication:

Option	Description	Required
`TenantDomain`	Your MonoCloud tenant domain URL (the token issuer)	Yes
`Audience`	The expected audience for token validation	Yes
`ClientId`	Client ID (required for token introspection)	No
`ClientAuth`	Client authentication method for introspection (see the introspection guide)	No
`IntrospectJwtTokens`	When `true`, JWT tokens are also introspected instead of validated locally	No
`RoleClaimType`	Token claim used for role/group checks (for example `groups`)	No
`ClockSkew`	Allowed clock drift during token validation	No

Next steps

Explore advanced protection patterns: