> ## 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 Signing Keys (JWKS) | Didit Authentication API

> GET /.well-known/jwks.json returns your application's public ES256 keys. Cache by kid; keys rotate every 30 days with a one-day overlap.

> [!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.

Keys rotate every 30 days, with a day of overlap on each side, so a JWKS cached for 5 minutes keeps verifying across a rotation. Fetch it again when a token names a `kid` you do not have, at most once a minute. See [Caching and rotation](https://docs.didit.me/authentication/tokens-and-jwks.md#caching-and-rotation).


## OpenAPI

````yaml openapi-authentication.json GET /.well-known/jwks.json
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/jwks.json:
    get:
      tags:
        - Issuer
      summary: Get the signing keys
      description: >-
        The application's public ES256 keys. Every token names its key in the
        `kid` header.


        Keys rotate every 30 days. The next key is published a day before it
        starts signing, and the previous key stays published for a day after it
        stops, so a JWKS cached for up to 5 minutes keeps verifying across a
        rotation. Cache keys by `kid` and fetch the JWKS again when a token
        names a `kid` you do not have, at most once a minute. When Didit revokes
        a compromised key, the key leaves this document at once and `GET
        /session/` rejects every token it signed. A replacement key starts
        signing immediately, without the day of advance publication, so a JWKS
        cached up to 5 minutes earlier still accepts the revoked key and does
        not know the replacement yet.
      operationId: authentication_get_jwks
      responses:
        '200':
          description: The published keys.
          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/JSONWebKeySet'
              examples:
                Keys:
                  summary: One signing key
                  value:
                    keys:
                      - kty: EC
                        crv: P-256
                        x: ZDN2unLMultuZwNY_ZKMvsKLRrlC_usPFZyK77cnDO8
                        'y': CfLKoaJNvhFpDWqG56H8dD_j0f1c93RdR63bhIdTh3I
                        kid: k_8sJ2dQvX0nLr5TfYb3HkPw
                        use: sig
                        alg: ES256
        '403':
          $ref: '#/components/responses/OriginNotAllowed'
        '404':
          $ref: '#/components/responses/ApplicationNotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/TemporarilyUnavailable'
      security:
        - {}
components:
  schemas:
    JSONWebKeySet:
      type: object
      description: >-
        The application's published public signing keys. Usually one key; two
        around a rotation, when the next key is published a day before it signs
        and the previous key stays a day after it stops.
      required:
        - keys
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/JSONWebKey'
    JSONWebKey:
      type: object
      description: A P-256 public key in JWK form (RFC 7517).
      required:
        - kty
        - crv
        - x
        - 'y'
        - kid
        - use
        - alg
      properties:
        kty:
          type: string
          enum:
            - EC
        crv:
          type: string
          enum:
            - P-256
        x:
          type: string
          description: The public point's x coordinate, base64url.
          example: ZDN2unLMultuZwNY_ZKMvsKLRrlC_usPFZyK77cnDO8
        'y':
          type: string
          description: The public point's y coordinate, base64url.
          example: CfLKoaJNvhFpDWqG56H8dD_j0f1c93RdR63bhIdTh3I
        kid:
          type: string
          description: >-
            Key ID, the `kid` in the header of every token this key signs. New
            key IDs start with `k_`.
          example: k_8sJ2dQvX0nLr5TfYb3HkPw
        use:
          type: string
          enum:
            - sig
        alg:
          type: string
          enum:
            - ES256
    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.