Authsignal’s session APIs can be used to manage an authenticated session for a user.

​
Configuration

​
Enabling the JWKS URL

To use Authsignal session APIs, you must first enable a JWKS URL in the Authsignal Portal under Settings -> API keys.
Enabling a JWKS URL
Once enabled, a link to the JWKS URL for your tenant will be displayed.
Enabling a JWKS URL

​
Creating app clients

Next, create an app client in the Authsignal Portal under Settings -> App clients.
Creating an app client
For each client you create, you can configure a separate access token and refresh token duration. The client ID will be set as the access token’s aud claim.
App client list

​
Creating sessions

In order to create an authenticated session, you must first obtain an Authsignal client token either by using a Client SDK or the pre-built UI.

​
OTP auth (email, SMS, TOTP)

For an OTP authentication method such as Email OTP you can follow the integration steps below to create a session. 1. Backend - Track action In your app’s backend, use an Authsignal Server SDK to track an action and obtain an initial client token. 
const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  action: "signIn",
  attributes: {
    email: "jane@authsignal.com",
  },
};

const response = await authsignal.track(request);

const token = response.token;
2. Frontend - Use a Client SDK In your web or mobile app, call setToken with the client token obtained in step 1, then use the relevant SDK methods to progress the user through a challenge and obtain a new client token. 
authsignal.setToken("eyJhbGciOiJ...");

// Send the user an email OTP code
// You can call this multiple times via a 'resend' button
await authsignal.email.challenge();

// Verify the inputted code matches the original code
const response = await authsignal.email.verify({ code: "123456" });

// Obtain a new token
const token = response.token;
3. Backend - Create session Pass the client token obtained in step 2 to your backend and exchange it for an access token and refresh token. 
const request = {
  token: "eyJhbGciOiJ...",
  clientId: "46e10ac5-cb9c-458f-ad86-0f698f67b365",
};

const response = await authsignal.createSession(request);

const accessToken = response.accessToken;
const refreshToken = response.refreshToken;

​
Passkeys

When using a device-bound authentication method like passkeys, only two steps are required to create a session. 1. Frontend - Use a Client SDK Use our web SDK to present a passkey sign-in prompt in the browser, or use one of our mobile SDKs to present the native passkey UI in an iOS or Android app. 
const response = await authsignal.passkey.signIn({
  action: "signInWithPasskey",
});

if (response.data?.token) {
  // Send token to your backend for validation
  const token = response.data.token;
} else {
  console.error("Passkey sign-in failed:", response.error);
}
2. Backend - Create session Pass the token obtained in step 1 to your backend and exchange it for an access token and refresh token. 
const request = {
  token: "eyJhbGciOiJ...",
  clientId: "46e10ac5-cb9c-458f-ad86-0f698f67b365",
};

const response = await authsignal.createSession(request);

const accessToken = response.accessToken;
const refreshToken = response.refreshToken;

​
Validating sessions

​
Using the JWKS URL

Access tokens are signed using an RS256 algorithm. A JWKS endpoint for your tenant’s keys is available at the following location: 
${env:AUTHSIGNAL_URL}/client/public/${env:AUTHSIGNAL_TENANT}/.well-known/jwks
  • The AUTHSIGNAL_URL value is the URL for your tenant’s region.
  • The AUTHSIGNAL_TENANT value is your tenant ID.

​
Using the SDK

You can also use the Authsignal Server SDK to validate an access token. 
const request = {
  accessToken: "eyJhbGciOiJ...",
  clientIds: ["46e10ac5-cb9c-458f-ad86-0f698f67b365"],
};

const response = await authsignal.validateSession(request);

const userId = response.user.userId;
const email = response.user.email;
In addition to verifying the access token’s signature, the Authsignal SDK’s validateSession method will also check that the token has not been revoked.

​
Refreshing sessions

A refresh token can be exchanged for a new access token and refresh token. 
const request = {
  refreshToken: "3f72a26e6834b4da...",
};

const response = await authsignal.refreshSession(request);

const accessToken = response.accessToken;
const refreshToken = response.refreshToken;
Refresh tokens are single-use and should be replaced with the new refresh token returned in the response.

​
Revoking sessions

An individual access token can be revoked so that the validateSession method will no longer accept it. 
const request = {
  accessToken: "eyJhbGciOiJ...",
};

await authsignal.revokeSession(request);
In addition, you can revoke all currently active tokens for a user. 
const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
};

await authsignal.revokeUserSessions(request);

​
Next steps