> ## 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 OpenID Configuration | Didit Authentication API

> GET /.well-known/openid-configuration returns your application's OpenID Connect discovery document: issuer, endpoints, grants, ES256 and claims.

> [!WARNING]
>
> Authentication is new. These endpoints are served by your application's issuer, such as `https://<name>.auth.didit.me`, and never take your Didit API key.

Fetch discovery from the issuer you configured, never from a URL you read in a token. The response can be cached for 5 minutes. See [Tokens and JWKS](https://docs.didit.me/authentication/tokens-and-jwks.md#discovery-and-keys) for what each field means for your integration.


## OpenAPI

````yaml openapi-authentication.json GET /.well-known/openid-configuration
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://<name>.auth.didit.me` for a live application, or
    `https://<name>.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 <access_token>`. 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
    {"<field>": "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": "<code>"}` | 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`.
    |

    | `{"<field>": ["<message>"]}` or `{"<field>": "<code>"}` | A request field
    failed validation. `non_field_errors` names a rule across fields, and
    `unknown_field` a field the endpoint does not accept. |

    | `{"detail": "<message>"}` | `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: `<name>.auth.didit.me` (live),
          `<name>.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:
  /.well-known/openid-configuration:
    get:
      tags:
        - Issuer
      summary: Get the OpenID configuration
      description: >-
        The issuer's discovery document: its endpoints, grants, signing
        algorithm and claims. Fetch it from the issuer you configured, never
        from a URL found in a token. Cache it for up to 5 minutes, as
        `Cache-Control` says.
      operationId: authentication_get_openid_configuration
      responses:
        '200':
          description: The discovery document.
          headers:
            Cache-Control:
              description: >-
                `public, max-age=300`: you and shared caches may keep a
                successful response for 5 minutes, one access token lifetime.
              schema:
                type: string
                example: public, max-age=300
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenIDConfiguration'
              examples:
                Discovery:
                  summary: A live application
                  value:
                    issuer: https://your-app.auth.didit.me
                    authorization_endpoint: https://your-app.auth.didit.me/sign-in
                    token_endpoint: https://your-app.auth.didit.me/token/
                    jwks_uri: https://your-app.auth.didit.me/.well-known/jwks.json
                    response_types_supported:
                      - code
                    response_modes_supported:
                      - query
                    grant_types_supported:
                      - authorization_code
                      - refresh_token
                    subject_types_supported:
                      - public
                    id_token_signing_alg_values_supported:
                      - ES256
                    token_endpoint_auth_methods_supported:
                      - none
                    code_challenge_methods_supported:
                      - S256
                    scopes_supported:
                      - openid
                      - email
                      - phone
                      - profile
                      - offline_access
                    claims_supported:
                      - iss
                      - aud
                      - sub
                      - sid
                      - auth_time
                      - nonce
                      - vendor_data
                      - amr
                      - org
                      - verified
                      - act
                      - email
                      - email_verified
                      - name
                      - phone_number
        '403':
          $ref: '#/components/responses/OriginNotAllowed'
        '404':
          $ref: '#/components/responses/ApplicationNotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/TemporarilyUnavailable'
      security:
        - {}
components:
  schemas:
    OpenIDConfiguration:
      type: object
      description: >-
        The issuer's OpenID Connect discovery document. Read endpoints from here
        rather than building them.
      required:
        - issuer
        - authorization_endpoint
        - token_endpoint
        - jwks_uri
        - response_types_supported
        - response_modes_supported
        - grant_types_supported
        - subject_types_supported
        - id_token_signing_alg_values_supported
        - token_endpoint_auth_methods_supported
        - code_challenge_methods_supported
        - scopes_supported
        - claims_supported
      properties:
        issuer:
          type: string
          format: uri
          description: >-
            The issuer: the application's sign-in origin, without a trailing
            slash. Every token's `iss` equals it.
          example: https://your-app.auth.didit.me
        authorization_endpoint:
          type: string
          format: uri
          description: The hosted sign-in page (`/sign-in`).
          example: https://your-app.auth.didit.me/sign-in
        token_endpoint:
          type: string
          format: uri
          example: https://your-app.auth.didit.me/token/
        jwks_uri:
          type: string
          format: uri
          example: https://your-app.auth.didit.me/.well-known/jwks.json
        response_types_supported:
          type: array
          items:
            type: string
          example:
            - code
        response_modes_supported:
          type: array
          items:
            type: string
          example:
            - query
        grant_types_supported:
          type: array
          items:
            type: string
          example:
            - authorization_code
            - refresh_token
        subject_types_supported:
          type: array
          items:
            type: string
          example:
            - public
        id_token_signing_alg_values_supported:
          type: array
          items:
            type: string
          example:
            - ES256
        token_endpoint_auth_methods_supported:
          type: array
          items:
            type: string
          description: '`none`: clients are public and send no secret.'
          example:
            - none
        code_challenge_methods_supported:
          type: array
          items:
            type: string
          example:
            - S256
        scopes_supported:
          type: array
          items:
            type: string
          example:
            - openid
            - email
            - phone
            - profile
            - offline_access
        claims_supported:
          type: array
          items:
            type: string
          example:
            - iss
            - aud
            - sub
            - sid
            - auth_time
            - nonce
            - vendor_data
            - amr
            - org
            - verified
            - act
            - email
            - email_verified
            - name
            - phone_number
    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:
    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

````

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