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-member claims within the JWT to Stytch platform attributes. The following attribute mappings are available today:
AttributeRequiredPurpose
emailYesThe email address of the member identified by the JWT
token_idYesA unique identifier for the JWT
organization_idNoThe Organization ID or external organization id of the member
external_member_idNoAn optional external member id to attach to the member
role_idsNoAn string array of RBAC Role IDs to assign to the member

​
JIT provisioning

By default, Trusted Auth Tokens cannot be used to create new members or organizations, and can only be used to authenticate an existing member. To allow Trusted Auth Tokens to create new members and organizations, 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.B2BClient({
  project_id: 'PROJECT_ID',
  secret: 'SECRET',
});

const params = {
  profile_id: "trusted-auth-token-profile-...",
  token: "eyJhb...",
  organization_id: "organization-..."
};

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
  • organization_id: tenant
  • 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",
  "tenant": "cust_56789",
  "jti": "tok_654321",
  "assignments": [
    "editor",
    "reader"
  ]
}
Can be exchanged to log in or create a Member with the following properties: 
{
  "member_id": "member-...",
  "external_id": "user_123456",
  "email": "ada.lovelace@example.com",
  "email_address_verified": true,
  "roles": [
    "stytch_member",
    "editor",
    "reader"
  ]
}
As well as a Member session with the following properties: 
{
  "member_id": "member-...",
  "organization_id": "organization-...",
  "authentication_factors": [
    {
      "delivery_method": "trusted_token_exchange",
      "trusted_auth_token_factor": {
        "token_id": "tok_654321"
      }
    }
  ]
}

​
What’s next