> ## Documentation Index
> Fetch the complete documentation index at: https://stytch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Trusted auth tokens overview

> Exchange signed JWTs for Stytch sessions to support external identity providers and custom auth factors.

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Issue or receive a token">
    Mint a JWT in your backend or accept one from a 3rd-party identity provider.
  </Step>

  <Step title="Exchange the token for a session">
    Call the [Attest Session endpoint](/api-reference/consumer/api/sessions/attest-session) to create or extend a Stytch session.
  </Step>
</Steps>

### Configuring a Trusted Auth Token profile

In the Stytch Dashboard, navigate to the [Trusted Auth Tokens](https://stytch.com/dashboard/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:

| Attribute          | Required | Purpose                                                                               |
| ------------------ | -------- | ------------------------------------------------------------------------------------- |
| email              | Yes      | The email address of the user identified by the JWT                                   |
| token\_id          | Yes      | A unique identifier for the JWT                                                       |
| external\_user\_id | No       | Optional [external user ID](/resources/migrations/external-ids) to attach to the user |
| role\_ids          | No       | Array of RBAC [Role IDs](/consumer-auth/authorization/create-rbac-policy) 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-reference/consumer/api/sessions/attest-session) API endpoint.
The API endpoint is available in all Stytch Backend and Frontend SDKs.

```js theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "user_id": "user-...",
  "authentication_factors": [
    {
      "delivery_method": "trusted_token_exchange",
      "trusted_auth_token_factor": {
        "token_id": "tok_654321"
      }
    }
  ]
}
```

***

## What's next

* Accept credentials from an [External Identity Provider](/consumer-auth/authentication/trusted-auth-tokens/external-idps)
* Create Trusted Auth Tokens for [custom auth factors](/consumer-auth/authentication/trusted-auth-tokens/custom-factors)
* Add [custom claims](/consumer-auth/manage-sessions/custom-claims) to session JWTs