> ## 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. # Get Session | Didit Authentication API > GET /session/ checks an access token against the live session: it fails at once after revocation, idle timeout, blocking or a refresh. > [!WARNING] > > Authentication is new. These endpoints are served by your application's issuer, such as `https://.auth.didit.me`, and never take your Didit API key. This is the instant revocation check. It allows 30 requests a minute and 300 an hour per IP address, so verify tokens offline on every request and call it before sensitive actions. See [Check the session](https://docs.didit.me/authentication/tokens-and-jwks.md#check-the-session). ## OpenAPI ````yaml openapi-authentication.json GET /session/ 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: /session/: get: tags: - Sessions summary: Get the session description: >- Checks the access token against the live session and returns it. Stricter than verifying the JWT yourself: it also fails at once when the session was revoked, went idle or passed its lifetime, when the person was blocked or their email is no longer verified, when the session no longer meets your MFA policy (for example after the person added an authenticator app or became an organization admin), or when the token was replaced by a refresh. Use it before a sensitive action, for example a payout. A successful check counts as activity, so it restarts the session's idle timeout. operationId: authentication_get_session responses: '200': description: The session is live. 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/Session' examples: Session: summary: A password session value: sub: 1c9d8b88-1bff-43d1-ad7a-88b2bc0024e9 sid: c9abf6cc-2d64-4bf2-b31e-a4d09a070ab1 application_id: 7b0a6c2e-3f41-4c9a-8d55-1e2f3a4b5c6d vendor_data: user-42 amr: - password mfa_verified: false email: person@example.com email_verified: true phone: null verified_identity: null verified: null expires_at: '2026-11-16T10:41:14.347557Z' post_logout_redirect_uri: '' organizations: [] VerifiedMember: summary: A verified organization member value: sub: 1c9d8b88-1bff-43d1-ad7a-88b2bc0024e9 sid: c9abf6cc-2d64-4bf2-b31e-a4d09a070ab1 application_id: 7b0a6c2e-3f41-4c9a-8d55-1e2f3a4b5c6d vendor_data: user-42 amr: - passkey mfa_verified: true email: person@example.com email_verified: true phone: '+34600000000' verified_identity: null verified: level: full_id over_18: true given_name: Alex country: ES expires_at: '2026-11-16T10:41:14.347557Z' post_logout_redirect_uri: https://app.example.com/ organizations: - organization_id: 3e9a1f0b-5c2d-4e7f-8a6b-9c0d1e2f3a4b organization__name: Northwind role: admin custom_role: null '401': $ref: '#/components/responses/InvalidToken' '403': $ref: '#/components/responses/OriginNotAllowed' '404': $ref: '#/components/responses/ApplicationNotFound' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/TemporarilyUnavailable' security: - AccessToken: [] components: schemas: Session: type: object description: The live session behind an access token. required: - sub - sid - application_id - vendor_data - amr - mfa_verified - email - email_verified - phone - verified_identity - verified - expires_at - post_logout_redirect_uri - organizations properties: sub: type: string format: uuid description: The identity ID. example: 1c9d8b88-1bff-43d1-ad7a-88b2bc0024e9 sid: type: string format: uuid description: The session ID. example: c9abf6cc-2d64-4bf2-b31e-a4d09a070ab1 application_id: type: string format: uuid example: 7b0a6c2e-3f41-4c9a-8d55-1e2f3a4b5c6d vendor_data: type: string description: The person's reference across Didit products, as in the tokens. example: user-42 amr: $ref: '#/components/schemas/AuthenticationMethods' mfa_verified: type: boolean description: >- Whether the session passed a second factor. Always `true` for a passkey sign-in. example: false email: type: string format: email nullable: true example: person@example.com email_verified: type: boolean example: true phone: type: string nullable: true description: E.164 phone number, or `null`. example: null verified_identity: $ref: '#/components/schemas/WalletVerification' verified: type: object nullable: true description: >- Verification level and selected claims, the same object the tokens carry as `verified`, or `null` when there is none. Read this, not `email_verified`, to know whether the person verified their identity. properties: level: type: string enum: - liveness - liveness_face_match - full_id description: >- The highest level passed. From weakest to strongest: `liveness`, `liveness_face_match`, `full_id`. example: full_id over_18: type: boolean example: true over_21: type: boolean example: true given_name: type: string example: Alex family_name: type: string example: Doe birthdate: type: string description: Date of birth from the document, `YYYY-MM-DD`. example: '1990-04-12' nationality: type: string description: ISO 3166-1 alpha-2 country code. example: ES country: type: string description: ISO 3166-1 alpha-2 code of the document's country. example: ES document_verified: type: boolean example: true liveness: type: boolean example: true expires_at: type: string format: date-time description: When the session ends at the latest. Idle timeout can end it sooner. example: '2026-11-16T10:41:14.347557Z' post_logout_redirect_uri: type: string description: >- Where your application sends the person after sign-out. Empty string when not set. example: https://app.example.com/ organizations: type: array description: >- Every customer organization the person belongs to, when organizations are on. Empty otherwise. items: $ref: '#/components/schemas/SessionOrganization' AuthenticationMethods: type: array description: >- How the session signed in, as one value: for example `password`, `code` (email code), `magic` (magic link), `passkey`, `phone`, `sso`, `wallet` (Didit ID Wallet) or the name of a social sign-in method. Empty for an agent token. items: type: string example: - password WalletVerification: type: object description: >- What the Didit ID Wallet shared at sign-in. `null` when the person signed in another way. nullable: true required: - issuer - subject properties: issuer: type: string description: The wallet's issuer. example: https://apx.didit.me/auth/idv subject: type: string description: The person's ID at the wallet. example: 8b7f5c1e-2d3a-4b5c-9e8f-7a6b5c4d3e2f shared_session: type: object description: >- A verification the person chose to share, which you redeem with your own API key. properties: share_token: type: string session_id: type: string from_application_id: type: string claims: type: object description: >- The verified facts the person agreed to share, limited to what your application asked for. additionalProperties: oneOf: - type: boolean - type: string example: over_18: true given_name: Alex SessionOrganization: type: object required: - organization_id - organization__name - role - custom_role properties: organization_id: type: string format: uuid example: 3e9a1f0b-5c2d-4e7f-8a6b-9c0d1e2f3a4b organization__name: type: string description: The organization's name. example: Northwind role: type: string enum: - admin - member - billing example: admin custom_role: type: object nullable: true description: The custom role assigned to the member, or `null`. required: - key - permissions properties: key: type: string example: approver permissions: type: array items: type: string example: - payouts.approve Detail: type: object required: - detail properties: detail: type: string example: invalid_token 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 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. TemporarilyUnavailable: description: >- A service the request depends on is briefly unavailable. Retry with backoff. 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: TemporarilyUnavailable: summary: Retry later value: error: temporarily_unavailable 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.