.NET Quickstart

This guide will help you integrate Descope's .NET SDK into your backend application. Follow the steps below to get started.

Install Backend SDK

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

Terminal

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.

If you plan to use Management functions, include a Descope Management Key here as well, which can be found on the Company Settings Page of the console.

appsettings.json

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

Setup Backend SDK

You'll need to initialize a DescopeClient object using your Project ID.

If you're using a custom domain with your Descope project, make sure to export the Base URL (e.g. export DESCOPE_BASE_URI="https://api.descope.com") when initializing descope_client.

Program.cs

using Descope;
using Microsoft.Extensions.Configuration;
 
// ... In your setup code
 
var config = new ConfigurationBuilder()
  .AddJsonFile("appsettings.json")
  .Build();
 
var descopeProjectId = config["Descope:ProjectId"];
var descopeManagementKey = config["Descope:ManagementKey"];
 
var descopeConfig = new DescopeConfig(projectId: descopeProjectId);
var descopeClient = new DescopeClient(descopeConfig);
{
    ManagementKey = descopeManagementKey,
};

Implement Session Validation

Note

If you need more granular control over session validation and prefer to use built-in Microsoft packages, see our .NET JWT Validation Guide for details on validating session tokens directly.

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

The frontend SDK will store the session token in either a cookie or your browser's local storage. If using a cookie, the token will be sent to your app server automatically with every request.

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.ValidateSession(sessionJwt);
}
catch (DescopeException e)
{
    // Handle the error
}

Once you've implemented the basic session validation, you can enhance your application with these additional features:

User Management

Learn how to create, update, and manage users in your application.

Role-Based Access Control

Implement fine-grained access control using roles and permissions.

API Gateway Session Validation

Secure your API endpoints with session validation middleware.

Set up M2M Authentication

Implement M2M authentication with Descope.

Additional Resources

Have You Implemented the Frontend Yet?

When integrating Descope into your application, you have three options depending on how much control you want over your frontend authentication experience and session management:

Option	Description	Best For
Use Descope Flows	Design your authentication screens and flows visually in the Descope Console with little or no frontend code. We handle all session management for you.	Fastest setup with minimal custom frontend work.
Use Descope Client SDKs	Build your own login screens and authentication experiences in your frontend using code, while relying on Descope's SDKs to manage sessions (login, logout, refresh).	Customizable UX with simplified session handling.
Use Descope Backend SDKs	Build your own frontend and your own backend APIs for authentication. You fully manage sessions, tokens, and authentication logic yourself.	Maximum flexibility and control, at the cost of more engineering effort.

Descope Flows

Design login screens and authentication flows visually without writing code, and embed them into your app.

Descope Client SDKs

Build custom login screens in your frontend using code, while we manage session tokens and refreshing for you.

Was this helpful?