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.

cURL

Create an Authorization Session

curl "https://api.warrant.dev/v1/sessions" \
    -X POST \
    -H "Authorization: ApiKey YOUR_KEY" \
    --data-raw \
    '{
        "type": "sess",
        "userId": "5djfs6",
    }'

Go

Create an Authorization Session

sessionToken, err := client.CreateAuthorizationSession(warrant.Session{
    UserId: userId,
})
if err != nil {
    // Handle error
}

Java

Create an Authorization Session

try {
    String sessionToken = client.createAuthorizationSession(Session.newAuthorizationSession(userId));
} catch (WarrantException e) {
    // Handle error
}

Node.js

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));

Python

Create an Authorization Session

try:
    session_token = client.create_authorization_session({ type: "sess", user_id: user_id })
except WarrantException:
    # Handle error

Ruby

Create an Authorization Session

begin
    session_token = Warrant::Session.create_authorization_session(user_id: user_id)
rescue
    # Handle error
end

Creating Self-Service Dashboard Sessions

cURL

Create a Self-Service Dashboard Session

curl "https://api.warrant.dev/v1/sessions" \
    -X POST \
    -H "Authorization: ApiKey YOUR_KEY" \
    --data-raw \
    '{
        "type": "ssdash",
        "userId": "5djfs6",
        "tenantId": "86slp7",
    }'

Go

selfServiceSessionUrl, err := client.CreateSelfServiceSession(
    warrant.Session{
        UserId: userId,
        TenantId: tenantId,
    },
    "https://your-website.com/account"
)
if err != nil {
    // handle error
}

Java

try {
    String selfServiceSessionUrl = client.createSelfServiceSession(Session.newSelfServiceSession(userId, tenantId), "https://your-website.com/account")
} catch (WarrantException e) {
    // Handle error
}

Node.js

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));

Python

Create a Self-Service Dashboard Session

self_service_session_url = client.create_self_service_session({ type: "ssdash", user_id: user_id, tenant_id: tenant_id }, "https://my-website.com/account")

Ruby

Create a Self-Service Dashboard Session

self_service_session_url = Warrant::Session.create_self_service_session("https://my-website.com/account", { user_id: user_id, tenant_id: tenant_id })

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:

• React
• Next.js
• Vue.js