Skip to main content

Creating Client Sessions

Warrant supports the use of short-lived, user-scoped sessions to grant limited access to the Warrant API. These tokens allow client applications (e.g. React apps, Mobile apps, etc.) to securely directly make requests to the Warrant API for a specific user. There are two types of client sessions:

  • Authorization Sessions are scoped to a single user and can only perform client-side authorization checks for that user.
  • Self-Service Dashboard Sessions are scoped to a single user and a single tenant. They can only be created for users with the view-self-service-dashboard permission (a predefined permission available by default in all accounts). These sessions allow your end users to manage the roles and permissions of other users in their tenant through the Self-Service Dashboard.

Creating Authorization Sessions

note

We recommend creating authorization sessions for your users during your login/sign-up flow. Once the session is created, you can return the generated session token to your client application along with any other information required for your normal login/sign-up process.

Create an Authorization Session

Using async/await
try {
const sessionToken = await warrantClient.Session.createAuthorizationSession({
userId: userId,
});
} catch (e) {
// Handle error
}
Using Promises
warrantClient.Session.
.createAuthorizationSession({ userId })
.then((sessionToken) => console.log(sessionToken))
.catch((error) => console.log(error));

Creating Self-Service Dashboard Sessions

Create a Self-Service Dashboard Session

Using async/await
try {
const selfServiceSessionUrl =
await warrantClient.Session.createSelfServiceSession(
{ userId: userId, tenantId: tenantId },
"https://my-website.com/account"
);
} catch (e) {
// Handle error
}
Using Promises
warrantClient.Session.createSelfServiceSession(
{ userId: userId, tenantId: tenantId },
"https://my-website.com/account"
)
.then((selfServiceUrl) => console.log(selfServiceUrl))
.catch((error) => console.log(error));

Identity Provider Sessions

Warrant supports the use of ID tokens issued by identity providers, such as Auth0 and Firebase. These tokens are in the form of a JSON Web Token (JWT) signed by your identity provider that can be verified with a public key containing authentication information about a particular user. This allows client applications to bypass the need to create a Warrant session by using your IdP tokens in place of a session token.

To get started with using your identity provider's tokens, configure your JSON Web Key Set (JWKS) endpoint in the Configuration section of your Account page. The endpoint should contain the set of public keys used to verify any JWTs issued by your provider. Currently, we only support JWTs that are signed using the RS256 signing algorithm.

Similar to Authorization Sessions, identity provider session tokens are scoped to the user being authenticated. By default, Warrant will make authorization checks using the sub claim of the JWT. For all authorization checks, the Warrant API will automatically set the subject of the warrant being checked to user:{sub}.

Common identity provider JWKS endpoints:

  • Auth0: https://{yourDomain}/.well-known/jwks.json
  • Google/Firebase: https://www.googleapis.com/oauth2/v3/certs

Refer to our guides to see how to use your IdP tokens: