.NET Quickstart

Install Backend SDK

Navigate to the .NET project directory which contains your .csproj file and install the SDK with dotnet using the following command:

dotnet add package Descope

Set up Environment file

Create a appsettings.json file in the root directory of your project with your Descope Project ID, which can be found on the Project Settings Page of the console.

{
  "Descope": {
    "ProjectId": "__ProjectID__",
    "ManagementKey": "DESCOPE_MANAGEMENT_KEY"
  }
}

Setup Backend SDK

You'll need to configure a DescopeClientOptions object using the values from your appsettings.json, then create the client using one of the two approaches below.

using Descope;
using Microsoft.Extensions.Configuration;

var config = new ConfigurationBuilder()
  .AddJsonFile("appsettings.json")
  .Build();

var options = new DescopeClientOptions
{
    ProjectId = config["Descope:ProjectId"],          // Required
    ManagementKey = config["Descope:ManagementKey"],  // Optional, for management APIs
    BaseUrl = "__BaseURL__",           // Optional, auto-detected; only set to override (e.g. custom domain)
    JwksCacheDuration = TimeSpan.FromMinutes(5)    // Optional, how long public signing keys are cached (default: 5 minutes)
};

Option 1: Dependency Injection

Best for ASP.NET Core apps. AddDescopeClient registers IDescopeClient as a singleton in the DI container, so you can inject it anywhere into your services. This keeps configuration in one place, hands lifetime management to the framework, and makes testing easier since IDescopeClient can be swapped for a mock in your unit tests.

builder.Services.AddDescopeClient(options);

public class MyService
{
    private readonly IDescopeClient descopeClient;

    public MyService(IDescopeClient client)
    {
        descopeClient = client;
    }
}

Option 2: Factory (instance-based)

Best for console apps, background workers, or when you need to manually control the client's lifetime. Create the client once and reuse that instance so key caching works across calls.

var descopeClient = DescopeManagementClientFactory.Create(options);

Implement Session Validation

You will need to fetch the session token from the Authorization header of each request, and use the SDK to validate the token.

The ValidateSession function can be used to verify a user's session as shown below. This either validates the sessions or throws an error, depending on if the JWT is valid or not.

// Validate the session. Will return an error if expired
try
{
    var sessionToken = await descopeClient.Auth.ValidateSessionAsync(sessionJwt);
}
catch (DescopeException e)
{
    // Handle the error
}