> ## 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. # Create Monitoring Token | Didit Authentication API > POST /monitoring-token/ swaps an access token for a 15-minute device credential bound to the person's vendor_data and browser origin. > [!WARNING] > > Authentication is new, and this endpoint stays off until Didit turns it on: until then it answers `503 monitoring_unavailable`. The browser and native SDKs call this endpoint from the person's device; your server does not need to. Every event sent with the credential is recorded for the person's `vendor_data`, whatever the device claims. ## OpenAPI ````yaml openapi-authentication.json POST /monitoring-token/ openapi: 3.0.3 info: title: Didit Authentication API version: 1.0.0 description: >- The server-facing endpoints of Didit Authentication, the sign-in product for your application's end users. Authentication is **new** and reaches production in the 2026-11-01 release. ## Base URL Every application is its own OpenID Connect issuer, and every endpoint below is served at the root of that issuer: - `https://.auth.didit.me` for a live application, or `https://.sandbox.auth.didit.me` for a sandbox application. - Your own custom domain, once it is active. It then replaces the default host as the issuer: new tokens name it in `iss`, discovery points at it and the publishable key changes. Access tokens issued under the default host fail `/session/`, `/step-up/` and `/monitoring-token/` until they are refreshed. Live and sandbox are separate applications, so they are separate issuers with separate keys. The publishable key is `pk_live_` (live) or `pk_test_` (sandbox) followed by the unpadded base64url encoding of the issuer, without a trailing slash: decode it to find the issuer. It is a public identifier, not a credential. The same JSON endpoints are also served under `https://apx.didit.me/auth/v2/authentication/{application_id}/`. Tokens always name the issuer above, whichever address issued them. ## Credentials These endpoints never take your Didit API key or a console token. - Discovery, the JWKS and `POST /token/` take no credential. Clients are public: there is no client secret, and an authorization code is bound to its PKCE verifier (`S256`). `client_id` is your application ID. - `/session/`, `/step-up/` and `/monitoring-token/` take the person's access token: `Authorization: Bearer `. Each successful call counts as activity on the session, so it restarts the session's idle timeout. ## Request bodies Every endpoint that takes a body accepts JSON, form-encoded and multipart bodies. This document lists JSON, plus form-encoded for `POST /token/` as OAuth clients send it. A field the endpoint does not accept gets `400 {"": "unknown_field"}`. ## Tokens - **Access token**: an ES256 JWT with header `typ: at+jwt`, valid for at most 5 minutes and never longer than its session. Claims: `AccessTokenClaims`. - **ID token**: an ES256 JWT with header `typ: JWT`. Claims: `IDTokenClaims`. It is never accepted as an access token. - **Refresh token**: a random string that rotates on every use. Sending a used refresh token again revokes the session. Verify a token with the keys from `GET /.well-known/jwks.json`: the algorithm must be `ES256`, `typ` must match the token type, `iss` must equal the issuer you configured and `aud` your application ID. Offline verification sees a revoked session only once its access token expires; `GET /session/` is the instant check. ## Errors | Body | When | | --- | --- | | `{"error": ""}` | Errors from `POST /token/`, all with status `400`, in the body shape of [RFC 6749 section 5.2](https://www.rfc-editor.org/rfc/rfc6749#section-5.2): `invalid_grant`, `invalid_client` and Didit's `mfa_required`. Service errors: `temporarily_unavailable`, `monitoring_unavailable`, `monitoring_disabled`. | | `{"": [""]}` or `{"": ""}` | A request field failed validation. `non_field_errors` names a rule across fields, and `unknown_field` a field the endpoint does not accept. | | `{"detail": ""}` | `401` (`invalid_token`), `403` (`origin_not_allowed`), `404` (unknown application or step-up) and `429` (rate limit). Also `400` for a body that cannot be parsed (`JSON parse error - ...`), `405` for a method the endpoint does not serve and `415` for an unsupported `Content-Type`. | A `401` also carries `WWW-Authenticate: Bearer`, and a `429` carries `Retry-After` in seconds. Two refusals are not JSON. An address that is not an issuer is refused before it reaches these endpoints, for example with an empty `404` for an unused `*.auth.didit.me` name. A `step_up_id` that is not a UUID gets a `404` page. ## Rate limits A request has to pass two layers. **Endpoint limits**, counted per client IP address, per application and per endpoint: - Discovery and the JWKS: 1,200 requests a minute and 12,000 an hour. - Every other endpoint: 30 requests a minute and 300 an hour. `GET` and `DELETE /session/` share one count. Over a limit: `429 {"detail": "Too many requests from this IP address. Please wait before trying again. Expected available in 60 seconds."}`, or `3600 seconds` for the hourly limit. **Bot protection**, on every `POST` and `DELETE`. Its buckets are shared by all of the application's `POST` and `DELETE` requests, the hosted sign-in steps included, and refill continuously: - 60 requests a minute per client IP address. - 30 requests a minute per device, for requests that identify their device, as the browser and native SDKs do. - 1,000 requests a minute for the whole application, across every IP address. Over a bucket: `429 {"detail": "rate_limited Expected available in N seconds."}` (`1 second.` when N is 1). The per-IP bucket spans endpoints, so one address that mixes token, step-up and sign-out calls can empty it before it reaches any endpoint limit. The application bucket counts every client of the application, browsers included. Both layers answer before the endpoint runs, so a request that got `429` did not run: retry it after `Retry-After`, a refresh included. ## Browser requests A request that carries an `Origin` header must come from one of the application's own origins or its allowed origins, or it gets `403 origin_not_allowed`. Server-to-server requests send no `Origin`. ## Not covered here These routes serve the hosted pages, the browser and native SDKs, and AI agents. They are not part of the server contract, and server SDKs do not call them: - Sign-in steps: `POST /authorize/`, `POST /password/`, `/email/*`, `/phone/*`, `/password-reset/*`, `/passkeys/*`, `/mfa/*`, `/social/*` and `/protection/complete/`. - Hosted pages and callbacks: `/sign-in`, `/magic`, `/invite`, `/reset`, `/verify/`, `/sso/*`, `/wallet/callback/`, `/logo/` and the native app association files under `/.well-known/`. - Agent access: `/agents/*` and `/grants/`, including `GET /agents/session/`, the live check for an AI agent's access token. Agent access is not part of this version of the contract. - The console management API for Authentication, which takes console sessions. Authentication events are not delivered as webhooks yet, so this document defines no webhook. servers: - url: https://{issuer} description: 'Your application''s issuer: its sign-in origin.' variables: issuer: default: your-app.auth.didit.me description: >- The issuer's host: `.auth.didit.me` (live), `.sandbox.auth.didit.me` (sandbox) or your active custom domain. security: [] tags: - name: Issuer description: Discovery and signing keys, to verify tokens. - name: Tokens description: The authorization code and refresh grants. - name: Sessions description: Check and end the session behind an access token. - name: Step-ups description: Verification before a sensitive action. - name: Monitoring description: Device credentials for transaction monitoring events. paths: /monitoring-token/: post: tags: - Monitoring summary: Create a monitoring token description: >- Swaps the person's access token for a short-lived device credential, so the person's browser or app can send activity events to transaction monitoring without your backend. The credential is bound to the person's `vendor_data` and to the request's `Origin`. The browser and native SDKs call this endpoint; server SDKs do not. It is off until Didit turns it on, and answers `503 monitoring_unavailable` until then. operationId: authentication_create_monitoring_token requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/MonitoringTokenRequest' example: {} responses: '201': description: A device credential for the person. headers: Cache-Control: description: 'Always `no-store`: never cache this response.' schema: type: string example: no-store Pragma: description: Always `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/MonitoringToken' examples: MonitoringToken: summary: A credential for the person's browser value: monitoring_token: mt_2f8c1d9e7b6a5f4e3d2c1b0a expires_at: '2026-10-17T10:56:14Z' allowed_event_categories: - session - gameplay - bonus - affiliate - payment - dispute - responsible_gambling - custom max_uses: 1000 bind_to_origin: https://app.example.com vendor_data: user-42 '400': description: The body carried a field. Send an empty object. headers: Cache-Control: description: 'Always `no-store`: never cache this response.' schema: type: string example: no-store Pragma: description: Always `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/FieldErrors' examples: UnknownField: summary: A field in the body value: vendor_data: unknown_field '401': $ref: '#/components/responses/InvalidToken' '403': $ref: '#/components/responses/OriginNotAllowed' '404': $ref: '#/components/responses/ApplicationNotFound' '409': description: >- Event monitoring is turned off for the application. Turn on event ingestion in the transaction monitoring settings. headers: Cache-Control: description: 'Always `no-store`: never cache this response.' schema: type: string example: no-store Pragma: description: Always `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/OAuthError' examples: MonitoringDisabled: summary: Event ingestion off value: error: monitoring_disabled '429': $ref: '#/components/responses/RateLimited' '503': description: >- Monitoring tokens are not enabled, or monitoring could not issue one (`monitoring_unavailable`), or a service the request depends on is briefly unavailable (`temporarily_unavailable`). Retry later. headers: Cache-Control: description: 'Always `no-store`: never cache this response.' schema: type: string example: no-store Pragma: description: Always `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/OAuthError' examples: MonitoringUnavailable: summary: Not available value: error: monitoring_unavailable TemporarilyUnavailable: summary: Retry later value: error: temporarily_unavailable security: - AccessToken: [] components: schemas: MonitoringTokenRequest: type: object description: 'Empty: the access token names the person.' additionalProperties: false properties: {} MonitoringToken: type: object description: >- A short-lived device credential for sending the person's activity events to transaction monitoring from their device. It is not tied to the session: it stays usable until `expires_at`, even after sign-out. required: - monitoring_token - expires_at - allowed_event_categories - max_uses - bind_to_origin - vendor_data properties: monitoring_token: type: string description: The device credential. Treat it as a secret. example: mt_2f8c1d9e7b6a5f4e3d2c1b0a expires_at: type: string format: date-time description: At most 15 minutes after it was issued. example: '2026-10-17T10:56:14Z' allowed_event_categories: type: array items: type: string description: >- The event categories it may send. Authentication and security events always come from Didit, never from the device. example: - session - gameplay - bonus - affiliate - payment - dispute - responsible_gambling - custom max_uses: type: integer example: 1000 bind_to_origin: type: string nullable: true description: >- The browser origin the credential works from: the request's `Origin`, or `null` when there was none. example: https://app.example.com vendor_data: type: string description: The person every event is recorded for, whatever the device sends. example: user-42 FieldErrors: title: Field errors type: object description: >- Validation errors by field. A value is a list of messages, or a single code (`unknown_field`, `invalid_redirect_uri`). `non_field_errors` holds rules across fields. additionalProperties: oneOf: - type: string - type: array items: type: string OAuthError: title: OAuth error type: object description: An OAuth error (RFC 6749 section 5.2) or a service error. required: - error properties: error: type: string example: invalid_grant Detail: type: object required: - detail properties: detail: type: string example: invalid_token responses: InvalidToken: description: >- The access token is missing, malformed, expired, signed by another issuer or key, an ID token, an agent token, or replaced by a refresh; or its session was revoked, idled out, passed its lifetime or no longer meets your MFA policy, or its person was blocked or their email is no longer verified. Send the person through sign-in again. headers: WWW-Authenticate: description: '`Bearer`.' schema: type: string example: Bearer Cache-Control: description: 'Always `no-store`: never cache this response.' schema: type: string example: no-store Pragma: description: Always `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: InvalidToken: summary: Rejected access token value: detail: invalid_token OriginNotAllowed: description: >- The request carried an `Origin` that is neither the application's own nor in its allowed origins. Server requests send no `Origin`. headers: Cache-Control: description: 'Always `no-store`: never cache this response.' schema: type: string example: no-store Pragma: description: Always `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: OriginNotAllowed: summary: Origin not allowed value: detail: origin_not_allowed ApplicationNotFound: description: >- The address belongs to an application, but Authentication is not active for it; on the `apx.didit.me` address, the application ID is unknown. An address that belongs to no application is refused before it reaches the endpoint, and that response is not JSON. headers: Cache-Control: description: 'Always `no-store`: never cache this response.' schema: type: string example: no-store Pragma: description: Always `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: ApplicationNotFound: summary: Unknown application value: detail: No Configuration matches the given query. RateLimited: description: >- Too many requests from this IP address for this endpoint, or, on a `POST` or `DELETE`, a bot protection bucket is empty. Nothing ran: wait `Retry-After` seconds, then retry. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 60 Cache-Control: description: 'Always `no-store`: never cache this response.' schema: type: string example: no-store Pragma: description: Always `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: RateLimited: summary: Endpoint limit value: detail: >- Too many requests from this IP address. Please wait before trying again. Expected available in 60 seconds. BotProtection: summary: Bot protection limit (POST and DELETE) value: detail: rate_limited Expected available in 2 seconds. securitySchemes: AccessToken: type: http scheme: bearer bearerFormat: JWT description: >- The person's access token from `POST /token/`: an ES256 JWT with header `typ: at+jwt`, valid for at most 5 minutes. Not your Didit API key. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.