> ## 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/b2b/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-member 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 member identified by the JWT                                                                         |
| `token_id`           | Yes      | A unique identifier for the JWT                                                                                               |
| `organization_id`    | No       | The Organization ID or [external organization id](/resources/migrations/external-ids) of the member                           |
| `external_member_id` | No       | An optional [external member id](/resources/migrations/external-ids) to attach to the member                                  |
| `role_ids`           | No       | An string array of RBAC [Role IDs](/multi-tenant-auth/enterprise-ready/rbac/create-rbac-policy#roles) 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-reference/b2b/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.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:

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

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

```json theme={null}
{
  "member_id": "member-...",
  "organization_id": "organization-...",
  "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](/multi-tenant-auth/authentication/trusted-auth-tokens/external-idps)
* Create Trusted Auth Tokens for [custom auth factors](/multi-tenant-auth/authentication/trusted-auth-tokens/custom-factors)
* Add [custom claims](/multi-tenant-auth/manage-sessions/custom-claims) to session JWTs