Skip to main content
Trusted Auth Tokens let you attest end-user identities by exchanging signed JWTs for Stytch sessions. Use them to integrate external identity providers or custom authentication factors without building bespoke OIDC/OAuth support.

​
Use cases

Trusted auth tokens support a range of powerful patterns:
  • 3rd-party SSO integrations: Exchange external identity provider tokens (like Vercel or Zendesk) for Stytch sessions.
  • Bring-your-own-auth: Accept JWTs your product already issues.
  • Custom auth factors: Add external factors (biometrics, device attestation) and represent them in the Stytch session.

​
How it works

1

Configure a Trusted Auth Token Profile

Define the JWT issuer and audience, add public key(s) or a JWKS URL, and map JWT claims to Stytch attributes.
2

Issue or receive a token

Mint a JWT in your backend or accept one from a 3rd-party identity provider.
3

Exchange the token for a session

Call the Attest Session endpoint to create or extend a Stytch session.

​
Configuring a Trusted Auth Token profile

In the Stytch 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:
AttributeRequiredPurpose
emailYesThe email address of the user identified by the JWT
token_idYesA unique identifier for the JWT
external_user_idNoOptional external user ID to attach to the user
role_idsNoArray of RBAC Role IDs to assign

​
JIT provisioning

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

​
Exchanging a Trusted Auth Token for a Session

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-...",
  token: "eyJhb...",
  session_duration_minutes: 60,
};

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

​
Putting it all together

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-...",
  "external_id": "user_123456",
  "emails": [
    {
      "email": "ada.lovelace@example.com",
      "email_id": "email-...",
      "verified": false
    }
  ],
  "roles": [
    "stytch_user",
    "editor",
    "reader"
  ]
}
as well as a User session with the following properties: 
{
  "user_id": "user-...",
  "authentication_factors": [
    {
      "delivery_method": "trusted_token_exchange",
      "trusted_auth_token_factor": {
        "token_id": "tok_654321"
      }
    }
  ]
}

​
What’s next