> ## 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

**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](https://stytch.com/docs/api-reference/consumer/api/sessions/attest-session.md) to create or extend a Stytch session.

### 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](https://stytch.com/docs/resources/migrations/external-ids.md) to attach to the user |
| role\_ids | No | Array of RBAC [Role IDs](https://stytch.com/docs/consumer-auth/authorization/create-rbac-policy.md) 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](https://stytch.com/docs/api-reference/consumer/api/sessions/attest-session.md) 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)
  });
```

Attested sessions are not mutable and cannot have new authentication factors added, and cannot have their duration extended.

## 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](https://stytch.com/docs/consumer-auth/authentication/trusted-auth-tokens/external-idps.md)
* Create Trusted Auth Tokens for [custom auth factors](https://stytch.com/docs/consumer-auth/authentication/trusted-auth-tokens/custom-factors.md)
* Add [custom claims](https://stytch.com/docs/consumer-auth/manage-sessions/custom-claims.md) to session JWTs
