Trusted Auth Tokens Overview

The Trusted Auth Tokens feature allows developers to attest end-user identities by exchanging signed JWTs for Stytch sessions. This gives teams the power to integrate custom authentication factors or external identity providers without needing bespoke code or full OIDC/OAuth support.

Use this feature to build flexible auth flows that use existing JWT infrastructure and securely interoperate with partners.

Trusted auth tokens support a range of powerful patterns:

• 3rd-party SSO integrations – Exchange external identity provider tokens (e.g., Vercel, Zendesk) for Stytch sessions.
• Bring-your-own-auth – Let your product issue its own ID tokens that Stytch accepts via a secure profile.
• Custom auth factors – Layer on external authentication (like biometric scans or hardware device attestation) and represent them in the Stytch session.

1. Configure a Trusted Auth Token Profile in the Stytch dashboard with:
   • JWT issuer and audience
   • Public key(s) or JWKS endpoint
   • Attribute mappings for session identity, external identifiers, and RBAC role assignments
2. Issue a token from your backend or accept one from a 3rd party.
3. Exchange the token using Stytch's API to start or extend a session.

In Dashboard, navigate to the Trusted Auth Tokens page. Here you can create a new Trusted Auth Token Profile for the provider of the tokens that you want to attest, or view and edit existing profiles.

The issuer (iss) and audience (aud) should match the corresponding values in the JWTs that you are trying to attest.

Attribute mappings are used to tie per-user claims within the JWT to Stytch platform attributes. The following attribute mappings are available today:

By default, Trusted Auth Tokens cannot be used to create new users. Trusted Auth Tokens can only be used to authenticate an existing user. To allow Trusted Auth Tokens to create new users, enable the Allow JIT Provisioning toggle in the dashboard.

Once you have a profile set up for the source of your trusted auth tokens, you can use the backend API to exchange a token for a Stytch session, or add it as an auth factor for an existing session using the Attest Session API endpoint. The API endpoint is available in all Stytch Backend and Frontend SDKs.

const stytch = require('stytch');

const client = new stytch.Client({
  project_id: 'PROJECT_ID',
  secret: 'SECRET',
});

const params = {
  profile_id: "trusted-auth-token-profile-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c",
  token: "eyJhb...",
  session_duration_minutes: 60,
};

client.sessions.attest(params)
  .then(resp => {
    console.log(resp)
  })
  .catch(err => {
    console.log(err)
  });

You can view the full Attest Session endpoint documentation here.

Suppose you configure a Trusted Auth Token Profile with an issuer of https://auth.example.com, an audience of https://api.example.com and the following attribute mapping:

• email: email
• token_id: jti
• external_user_id: sub
• roles: assignments

A JWT with the following claims:

{
  "iss": "https://auth.example.com",
  "aud": "https://api.example.com",
  "sub": "user_123456",
  "email": "ada.lovelace@example.com",
  "jti": "tok_654321",
  "assignments": [
    "editor",
    "reader"
  ]
}

Can be exchanged to log in or create a user with the following properties:

{
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "external_id": "user_123456",
  "emails": [
    {
      "email": "ada.lovelace@example.com",
      "email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
      "verified": false
    }
  ],
  "roles": [
    "stytch_user",
    "editor",
    "reader"
  ]
}

as well as a session with the following properties:

{
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "authentication_factors": [
    {
      "delivery_method": "trusted_token_exchange",
      "trusted_auth_token_factor": {
        "token_id": "tok_654321"
      }
    }
  ]
}

Read on for next steps:

• Accept credentials from an External Identity Provider
• Create custom JWTs using Private Keys
• Add custom claims to your Stytch session JWTs using Custom Claim Templates