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

# Authentication Integration Guide: Architecture and Go-Live

> How a production Didit Authentication integration fits together: hosted or own screens, token storage, backend checks, sessions, native apps and go-live.

This guide explains how a production Didit Authentication integration fits together, from the first redirect to the go-live checklist.
Start with the [quickstart](https://docs.didit.me/authentication/quickstart.md) if you have not signed a person in yet, and use the platform quickstarts for the code of each SDK.

## Architecture

```mermaid theme={null}
sequenceDiagram
    participant App as Your app (browser or mobile)
    participant Hosted as Your Didit sign-in origin
    participant API as Your backend
    participant Webhook as Your webhook endpoint

    App->>Hosted: Open /sign-in (redirect_uri, state, PKCE challenge)
    Note over Hosted: Sign-in method, MFA,<br/>bot protection, verification
    Hosted-->>App: Redirect to redirect_uri with code and state
    App->>Hosted: POST /token/ (code, PKCE verifier)
    Hosted-->>App: Access token (5 min), ID token, refresh token
    App->>API: Request with Authorization: Bearer access token
    Note over API: Verify the signature<br/>with the cached JWKS
    API->>Hosted: GET /session/ before a sensitive action
    Hosted-->>API: Live session, or 401
    Hosted->>Webhook: auth.signup, auth.login, auth.new_device ...
```

Four parts are involved:

| Part | Owns |
| - | - |
| Your app | Starting sign-in, keeping the PKCE verifier and `state`, holding the tokens, and sending the access token to your backend. The SDKs do all of it. |
| Your sign-in origin | `https://<slug>.auth.didit.me` (or your [custom domain](https://docs.didit.me/authentication/branding-and-custom-domain.md#custom-domain)): the hosted pages, the token endpoint, the session, discovery and the signing keys. |
| Your backend | Verifying the access token on every protected request, checking the session before sensitive actions, and deciding what the person may do. |
| Didit console and webhooks | Configuration, the people and their sessions, sign-in events, and the `auth.*` webhooks your server subscribes to. |

No Didit API key and no secret ever belongs in your app: the publishable key is public, and the code exchange is protected by PKCE instead of a client secret.

## Hosted pages or your own screens

Choose where people type their email, password or code.
The setting is `sign_in_ui` (`hosted` by default, or `own`), and you can change it later.

| | Hosted pages (recommended) | Your own screens |
| - | - | - |
| What you build | A sign-in button and a callback page. | Every screen and every intermediate step. |
| Methods | All of them, including magic links, company SSO and passkeys. | Password, email code, phone code, MFA and protection challenges through the SDKs' headless methods. Magic links run on the hosted pages only. |
| Next steps | Handled for you: MFA, MFA enrollment, protection challenges and verification at sign-up. | Your screens handle `mfa_required`, `mfa_enrollment_required`, `protection_required` and `verification_required`. See [sign-in methods](https://docs.didit.me/authentication/sign-in-methods.md). |
| Brand | Your logo, colors and texts from [branding](https://docs.didit.me/authentication/branding-and-custom-domain.md). | Entirely yours. |
| Setup | Redirect URLs. | Redirect URLs, plus your web origin in **Allowed origins**. |

Passkeys belong to your application's sign-in origin.
The SDKs' passkey methods work only on pages served from that origin, so on your own screens on another domain, send people to the hosted page for passkeys.

## Choose your SDK

| Your app | Package | Where tokens live |
| - | - | - |
| Single-page web app | [`@didit-protocol/auth`](https://docs.didit.me/authentication/quickstarts/javascript) or [`@didit-protocol/auth-react`](https://docs.didit.me/authentication/quickstarts/react) | Web storage or memory in the browser. Keep a strict Content Security Policy. |
| Server-rendered web app | [`@didit-protocol/auth-nextjs`](https://docs.didit.me/authentication/quickstarts/nextjs) | HttpOnly cookies set by your server. The page never sees the tokens. |
| iOS | [`DiditAuth`](https://docs.didit.me/authentication/quickstarts/ios) | The Keychain. |
| Android | [`me.didit:didit-auth`](https://docs.didit.me/authentication/quickstarts/android) | Storage protected by the Android Keystore. |
| React Native or Flutter | [`@didit-protocol/auth-react-native`](https://docs.didit.me/authentication/quickstarts/react-native) or [`didit_auth`](https://docs.didit.me/authentication/quickstarts/flutter) | The platform's protected storage, through the native modules. |
| Any backend | [Server SDKs](https://docs.didit.me/integration/server-sdks/overview.md), `verifyToken` from `@didit-protocol/auth/server`, or any JWT library | Nothing to store: it verifies the token it receives. |

Without an SDK, implement the authorization code flow with PKCE yourself: the [JavaScript quickstart](https://docs.didit.me/authentication/quickstarts/javascript.md#without-the-sdk) shows the whole contract.

## Protect your backend

A frontend session check only controls what you show.
Your backend makes every decision from a verified token.

1. **Verify the access token on every request.** Check the ES256 signature against your issuer's JWKS, then `iss`, `aud`, `exp` and `typ: at+jwt`, and reject a token whose `act` is not `null` unless the route accepts [AI agents](https://docs.didit.me/authentication/agent-access.md). See [verify a token on your server](https://docs.didit.me/authentication/tokens-and-jwks.md#verify-a-token-on-your-server).
2. **Check the live session before a sensitive action.** An access token stays valid until it expires, within 5 minutes. `GET /session/` fails at once when the session was revoked, went idle or expired, when the person was blocked, or when the session no longer meets your MFA policy. See [check the session](https://docs.didit.me/authentication/tokens-and-jwks.md#check-the-session).
3. **Ask for a step-up when the action is risky.** Before a payout, a new bank account or an email or phone change, ask Didit whether the person has to verify again, and act only on an `approved` step-up that your backend read itself. See [step-up before sensitive actions](https://docs.didit.me/authentication/verified-identity.md#step-up-before-sensitive-actions).
4. **Take `vendor_data` from the verified token**, never from a field the browser sent, and use it for the person's verifications and transactions.

## Sessions

| Event | What happens |
| - | - |
| Sign-in | A session starts. Its length is your `session_lifetime` (30 days by default) and it ends earlier after `idle_timeout` without activity (1 day by default). |
| Every few minutes | The SDK refreshes the access token, which lasts at most 5 minutes. The refresh token rotates: each one works once. |
| A used refresh token is sent again | Didit treats it as theft and ends the session. Run one refresh at a time per session. |
| Sign-in on another device | With `multiple_sessions: false`, the person's other sessions end. |
| Password reset | Every session ends when `revoke_on_password_change` is on (the default). |
| Sign-out | `DELETE /session/` ends the session, and your app sends the person to your `post_logout_redirect_uri`. |
| Your team acts | The console can revoke one session, sign a person out everywhere, or block them. See the [console guide](https://docs.didit.me/authentication/console.md#sign-ins-and-sessions). |

Change the lengths in **Authentication > Security and sessions**, or by API in [application settings](https://docs.didit.me/authentication/overview.md#application-settings).

![The Active sessions view in the Didit Business Console, listing signed-in sessions with device, location, start, last activity, end and a Revoke button](https://mintcdn.com/didit-0f962782/RpqZjIB1GnUPdMTN/images/authentication/console-active-sessions.png?fit=max\&auto=format\&n=RpqZjIB1GnUPdMTN\&q=85\&s=098f6be31804b0af7c680e569f341bfb)

Authentication > Sign-ins > Active sessions, with Revoke on each session.

## Native apps

Didit returns people to a native app through an HTTPS redirect only: it accepts no custom URL schemes.

* **iOS:** make the redirect an associated domain, with `webcredentials` in your `apple-app-site-association`.
* **Android:** make the redirect an App Link, with your `assetlinks.json`.
* Register every redirect URL under **Authentication > Security and sessions**, like a web callback.

For passkeys in your app, register the apps that share your application's passkeys with `PUT native-apps/` on the [Authentication management API](https://docs.didit.me/authentication/set-up-by-api.md).
Didit then lists them in the `apple-app-site-association` and `assetlinks.json` it serves on your sign-in origin.
`MANAGEMENT_BASE` is your application's management API address, and an API key with the `authentication` scope at **write** can make the call.
The call replaces both lists, so send both:

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}native-apps/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ios_app_ids": ["ABCDE12345.com.example.app"],
    "android_apps": [
      {
        "package_name": "com.example.app",
        "sha256_cert_fingerprints": ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
      }
    ]
  }'
```

| Field | Rule |
| - | - |
| `ios_app_ids` | Up to 10 entries of your Team ID and bundle identifier, for example `ABCDE12345.com.example.app`. |
| `android_apps` | Up to 10 apps, each with its `package_name` and 1 to 5 SHA-256 signing-certificate fingerprints. |

The [iOS](https://docs.didit.me/authentication/quickstarts/ios.md) and [Android](https://docs.didit.me/authentication/quickstarts/android.md) quickstarts show the app side.

## Connect identity verification and transaction monitoring

Every person has one `vendor_data` value, in their tokens and their session.
Use it as `vendor_data` when you [create a verification session](https://docs.didit.me/sessions-api/create-session.md) or [submit a transaction](https://docs.didit.me/transaction-monitoring/transactions.md), and the console shows sign-ins, verifications and transactions on the same person.

* To verify people at sign-up or again before a payout without building a verification flow, use [verified identity](https://docs.didit.me/authentication/verified-identity.md).
* Sign-in events reach [event rules](https://docs.didit.me/transaction-monitoring/event-rules.md) and the fraud views automatically. Do not post your own `auth.login` events for the same sign-ins.
* A successful sign-in never approves a verification or a transaction: handle each product's decision separately.

See [keep one person across products](https://docs.didit.me/authentication/overview.md#keep-one-person-across-products).

## Receive sign-in events

Subscribe a [webhook destination](https://docs.didit.me/integration/webhooks.md) to the `auth.*` types you need, such as `auth.new_device` or `auth.account_locked`.
Deduplicate on `auth_event.event_id`, and verify the signature as for every Didit webhook.
See [events and webhooks](https://docs.didit.me/authentication/events-and-webhooks.md) for every type and its payload.

## Move existing users

If your users already have accounts on another identity platform or in your own database, [import them](https://docs.didit.me/authentication/migration.md) before you switch sign-in.
Import their password hashes where the source gives them, keep their social links, and keep your own user IDs as `external_id`, which becomes their `vendor_data`.
Nothing changes for them until you switch your app to Didit.

## Go-live checklist

1. Authentication is turned on for your Live application on the **Products** page.
2. Your production `https://` redirect URLs and allowed origins are registered on the Live application. A Live application accepts no `http://` addresses.
3. Each social sign-in method uses your own app's client ID and secret: Didit's test credentials work in Sandbox only.
4. Your production configuration has the Live publishable key (`pk_live_`) and your Live issuer.
5. Your MFA policy, session lifetime, idle timeout, password length and sign-up policy are what you want. See [application settings](https://docs.didit.me/authentication/overview.md#application-settings).
6. [Bot protection](https://docs.didit.me/authentication/bot-protection.md) is on, with the breached-password check.
7. Your backend verifies every access token, and calls `GET /session/` before sensitive actions.
8. Your branding, page texts and terms and privacy links are set. If you plan a [custom domain](https://docs.didit.me/authentication/branding-and-custom-domain.md#custom-domain), activate it before people start adding passkeys.
9. Your webhook destination is subscribed to the `auth.*` types you handle.
10. You tested sign-up, returning sign-in, cancellation, forgot password, MFA, session expiry, sign-out and a revoked session on the Live application.

## Troubleshooting

| Symptom | Cause and fix |
| - | - |
| Every runtime route answers `404` | Authentication is off for the application, or the address mixes a sandbox and a live origin. Turn it on from the **Products** page, and use the origin your publishable key names. |
| The sign-in page answers `400` and asks you to register an address, or `POST /authorize/` answers `invalid_redirect_uri` | The `redirect_uri` is not registered exactly: scheme, host, port, path and query must match character by character. See [redirect URLs](https://docs.didit.me/authentication/overview.md#redirect-urls). |
| A browser call to your sign-in origin answers `403` with `origin_not_allowed` | Your web origin is not in **Allowed origins**. Add it with no path and no trailing slash. |
| `POST /token/` answers `invalid_grant` | The code was already used, is older than 60 seconds, or was sent with another PKCE verifier or `redirect_uri`. For a refresh, the refresh token was already used, which ends the session. Start sign-in again. |
| A password sign-in answers `invalid_credentials` with the right password | The email is not verified, or the account is locked or blocked. Didit gives the same answer on purpose. Check the person in **Users**. |
| `GET /session/` answers `401` | The session was revoked, went idle or expired, the person was blocked, the token was replaced by a refresh, or the session no longer meets your MFA policy. Refresh the token, or sign the person in again. |
| Adding a passkey or an authenticator answers `403 reauthentication_required` | These need a session created in the last 5 minutes. Sign the person in again first. |
| A phone code answers `503 delivery_unavailable` | The code could not be delivered. Let the person retry, or offer another method. |
| A call answers `429` | You hit a rate limit. Retry after the time in `Retry-After`. See [rate limits](https://docs.didit.me/authentication/bot-protection.md#rate-limits). |
| A setup call with an API key answers `409 product_disabled` | Authentication is off for the application. A person turns it on in the console. |
| A call answers `403 plan_required` | The feature, such as custom roles or company SSO setup links, needs the Scale or Enterprise plan. Sandbox applications have it on any plan. |
| Tokens fail after you activated a custom domain | The issuer and the publishable key changed. Copy the new key into your app, and update the issuer your backend checks. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.