Descope 1.8.0

Descope .NET SDK

A .NET SDK for integrating with the Descope authentication and user management platform.

Installation

dotnet add package Descope

Client Configuration

Configure the Descope client using DescopeClientOptions:

var options = new DescopeClientOptions
{
    ProjectId = "your-project-id",           // Required
    ManagementKey = "your-management-key",   // Optional, for management APIs
    AuthManagementKey = "your-auth-key",     // Optional, for accessing disabled auth APIs
    BaseUrl = "https://api.descope.com",     // Optional, auto-detected from project ID
    FgaCacheUrl = "https://fga.example.com", // Optional, if using the Descope FGA Cache Docker Container
    IsUnsafe = false,                        // Optional, for dev/test only
    JwksCacheDuration = TimeSpan.FromMinutes(5) // Optional, how long public signing keys are cached (default: 5 minutes)
};

Creating the Client

Using Dependency Injection (Recommended)

services.AddDescopeClient(new DescopeClientOptions
{
    ProjectId = "your-project-id",
    ManagementKey = "your-management-key"
});

// Inject IDescopeClient in your services
public class MyService
{
    private readonly IDescopeClient _client;
    
    public MyService(IDescopeClient client)
    {
        _client = client;
    }
}

Using Factory (Instance-based)

var client = DescopeManagementClientFactory.Create(new DescopeClientOptions
{
    ProjectId = "your-project-id",
    ManagementKey = "your-management-key"
});

Usage Examples

Authentication API Call

// Verify a magic link token
var response = await client.Auth.V1.Magiclink.Verify.PostAsync(
    new VerifyMagicLinkRequest { Token = "magic-link-token" });

Management API V1 Call

// Create a test user
var user = await client.Mgmt.V1.User.Create.Test.PostAsync(
    new CreateUserRequest
    {
        Identifier = "user@example.com",
        Email = "user@example.com",
        VerifiedEmail = true
    });

Management API V2 Call

// Search users
var searchResponse = await client.Mgmt.V2.User.Search.PostAsync(
    new SearchUsersRequest { Limit = 10 });

Management Flows

Management flows allow you to run server-side flows with custom input and receive dynamic output. The SDK provides a convenient extension method that deserializes the output as JSON for easy access.

// Run a management flow with custom input
var request = new RunManagementFlowRequest
{
    FlowId = "my-management-flow",
    Options = new ManagementFlowOptions
    {
        Input = new ManagementFlowOptions_input
        {
            AdditionalData = new Dictionary<string, object>
            {
                { "email", "user@example.com" },
                { "customParam", "customValue" }
            }
        }
    }
};

var response = await client.Mgmt.V1.Flow.Run.PostWithJsonOutputAsync(request);

// Access JSON properties directly using JsonElement
var root = response.OutputJson!.Value;
var email = root.GetProperty("email").GetString();

// Access nested objects using standard JsonElement methods
var greeting = root.GetProperty("obj").GetProperty("greeting").GetString();
var count = root.GetProperty("obj").GetProperty("count").GetInt32();
var enabled = root.GetProperty("obj").GetProperty("enabled").GetBoolean();

Token Validation

The SDK provides three methods for working with session tokens:

ValidateSessionAsync

Validates a session JWT locally using cached public keys. The public signing keys (JWKS) are fetched from the server and cached, so most validations do not make a network call.

var token = await client.Auth.ValidateSessionAsync(sessionJwt);
// Returns Token with claims, subject, expiration, etc.

Public key (JWKS) caching

Fetched keys are cached for DescopeClientOptions.JwksCacheDuration (default 5 minutes). Once the duration elapses, the next validation refreshes the keys; refreshes are lazy (triggered on the next validation), not on a background timer. To reduce key-fetch requests on high-traffic services, increase the duration:

var options = new DescopeClientOptions
{
    ProjectId = "your-project-id",
    JwksCacheDuration = TimeSpan.FromMinutes(30)
};

Raising this value is safe even during key rotation: if a token is signed with a key ID that is not already cached, the SDK performs an immediate key re-fetch (bypassing the cache duration) and retries validation once, so tokens from newly rotated keys are accepted right away. JwksCacheDuration must be greater than zero.

Note: For the cache to persist across requests, reuse a single IDescopeClient instance. The DI registration (AddDescopeClient) registers it as a singleton for you.

RefreshSessionAsync

Refreshes an expired session using a refresh JWT. This method makes a remote API call to generate a new session token.

var newToken = await client.Auth.RefreshSessionAsync(refreshJwt);
// Returns a new session Token with updated expiration

ValidateAndRefreshSession

Attempts to validate the session JWT first (locally), and if that fails or the session is empty, falls back to refreshing using the refresh JWT (remote call).

var token = await client.Auth.ValidateAndRefreshSession(sessionJwt, refreshJwt);
// Returns valid Token, using local validation when possible

Performance Note: Validation calls (ValidateSessionAsync, ValidateAndRefreshSession) are highly efficient as they use locally cached public keys. Only RefreshSessionAsync and the refresh fallback in ValidateAndRefreshSession make remote API calls.

Authenticated User Operations

Some authentication operations require an authenticated user context and must be called with a refresh JWT. For these operations, use the PostWithJwt extension methods that explicitly require the refresh token.

Example: Update User Email

// Update user email using magic link (requires refresh JWT)
var response = await client.Auth.V1.Magiclink.Update.Email.PostWithJwtAsync(
    new UpdateUserEmailMagicLinkRequest
    {
        Email = "newemail@example.com",
        RedirectUrl = "https://myapp.com/verify"
    },
    refreshJwt);

Other operations requiring PostWithJwt include, among others: updating phone numbers, passwords, TOTP settings, WebAuthn devices, and getting user details via the /me endpoint.

ASP.NET OIDC Integration

For ASP.NET Core applications, use the AddDescopeOidcAuthentication extension method to integrate Descope as your Identity Provider (IdP) using OpenID Connect (OIDC):

builder.Services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
    .AddDescopeOidcAuthentication(options =>
    {
        options.ProjectId = "your-project-id";
    });

See the OIDC Demo Application for a complete working example with additional customization options.

For Maintainers

If you're maintaining or contributing to this SDK, see the Maintainer Guide for detailed information about code generation, extension methods, testing, and development workflows.