/
Contact usSee pricingStart building

    About B2B SaaS Authentication

    Introduction
    Stytch B2B Basics
    Integration Approaches
      Full-stack overview
      Frontend (pre-built UI)
      Frontend (headless)
      Backend
    Next.js
      Routing
      Authentication
      Sessions
    Migrations
      Overview
      Reconciling data models
      Migrating user data
      Additional migration considerations
      Zero-downtime deployment
      Defining external IDs
      Migrating from Stytch Consumer to B2B
      Exporting from Stytch
    Custom Domains
      Overview

    Authentication

    Single Sign On
    • Resources

      • Overview
        External SSO Connections
        Standalone SSO
    • Integration Guides

      • Start here
        Provider setup
        Backend integration guide
        Headless integration guide
        Pre-built UI integration guide
    OAuth
    • Resources

      • Overview
        Authentication flows
        Identity providers
        Google One Tap
        Provider setup
    • Integration Guides

      • Start here
        Backend integration
        Headless frontend integration
        Pre-built UI frontend integration
    Connected Apps
      Overview
      Getting started with the SDK
      Getting started with the API
      Client types
      OAuth scopes
    • Integration Guides

      • Integrate with an Existing Auth System
        MCP Authorization Overview
        Integrate with a remote MCP server
        Integrate with AI agents
    • Resources

      • Consent Management
        Custom Domains
        Testing Integrations
    Sessions
    • Resources

      • Overview
        JWTs vs Session Tokens
        How to use Stytch JWTs
        Custom Claims
        Custom Claim Templates
    • Integration Guides

      • Start here
        Backend integration
        Frontend integration
    Email OTP
      Overview
    Magic Links
    • Resources

      • Overview
        Email Security Scanner Protections
    • Integration Guides

      • Start here
        Backend integration
        Headless frontend integration
        Pre-built UI frontend integration
    Multi-Factor Authentication
    • Resources

      • Overview
    • Integration Guides

      • Start here
        Backend integration
        Headless frontend integration
        Pre-built UI frontend integration
    Passwords
    • Resources

      • Overview
        Strength policy
    • Integration Guides

      • Pre-built UI frontend integration
    UI components
      Overview
      Implement the Discovery flow
      Implement the Organization flow
    DFP Protected Auth
      Overview
      Setting up DFP Protected Auth
      Handling challenges
    M2M Authentication
      Authenticate an M2M Client
      Rotate client secrets
      Import M2M Clients from Auth0
    Trusted Auth Tokens
      Overview
      Getting Started with External IDPs
      Getting Started with Custom Auth Factors
    Device History
      New device notifications

    Authorization & Provisioning

    RBAC
    • Resources

      • Overview
        Stytch Resources & Roles
        Role assignment
    • Integration Guides

      • Start here
        Backend integration
        Headless frontend integration
    SCIM
    • Resources

      • Overview
        Supported actions
    • Integration Guides

      • Using Okta
        Using Microsoft Entra
    Organizations
      Managing org settings
      JIT Provisioning

    Testing

    E2E testing
    Sandbox values
Get support on SlackVisit our developer forum

Contact us

B2B SaaS Authentication

/

Guides

/

Authentication

/

Trusted Auth Tokens

/

Overview

Trusted Auth Tokens Overview

The Trusted Auth Tokens feature allows developers to attest end-user identities by exchanging signed JWTs for Stytch sessions. This gives teams the power to integrate custom authentication factors or external identity providers without needing bespoke code or full OIDC/OAuth support.

Use this feature to build flexible auth flows that use existing JWT infrastructure and securely interoperate with partners.


Use cases

Trusted auth tokens support a range of powerful patterns:

  • 3rd-party SSO integrations – Exchange external identity provider tokens (e.g., Vercel, Zendesk) for Stytch sessions.
  • Bring-your-own-auth – Let your product issue its own ID tokens that Stytch accepts via a secure profile.
  • Custom auth factors – Layer on external authentication (like biometric scans or hardware device attestation) and represent them in the Stytch session.

How it works

  1. Configure a Trusted Auth Token Profile in the Stytch dashboard with:
    • JWT issuer and audience
    • Public key(s) or JWKS endpoint
    • Attribute mappings for session identity, external identifiers, and RBAC role assignments
  2. Issue a token from your backend or accept one from a 3rd party.
  3. Exchange the token using Stytch's API to start or extend a session.

Setting up a Trusted Auth Token Profile

In 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_idThe Organization ID or external organization id of the member
external_member_idAn optional external member id to attach to the member
role_idsAn 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. Trusted Auth Tokens can only be used to authenticate an existing member. To allow Trusted Auth Tokens to create new members and organizations, enable the Allow JIT Provisioning toggle 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 = {
  organization_id: "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
  profile_id: "trusted-auth-token-profile-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c",
  token: "eyJhb...",
};

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

You can view the full Attest Session endpoint documentation here.


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-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
  "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-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
  "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
  "authentication_factors": [
    {
      "delivery_method": "trusted_token_exchange",
      "trusted_auth_token_factor": {
        "token_id": "tok_654321"
      }
    }
  ]
}

What's next

Read on for next steps:

  • Accept credentials from an External Identity Provider
  • Create custom JWTs using Private Keys
  • Add custom claims to your Stytch session JWTs using Custom Claim Templates

Use cases

How it works

Setting up a Trusted Auth Token Profile

JIT Provisioning

Exchanging a Trusted Auth Token for a Session

Putting it all together

What's next