> ## 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.

# 获取 OpenID 配置（发现文档）| Didit Authentication API

> Didit 的 GET /.well-known/openid-configuration 接口返回您应用的 OpenID Connect 发现文档：issuer、endpoint、授权类型、ES256 和声明。

> [!WARNING]
>
> 身份验证功能是新推出的。这些端点由您应用的签发方提供，例如 `https://<name>.auth.didit.me`，并且绝不接受您的 Didit API 密钥。

请始终从您配置的签发方获取发现文档，切勿从令牌中读取的 URL 获取。响应可缓存 5 分钟。有关每个字段对您的集成意味着什么，请参阅[令牌与 JWKS](https://docs.didit.me/zh/authentication/tokens-and-jwks.md#发现与密钥)。


## OpenAPI

````yaml zh/openapi-authentication.json GET /.well-known/openid-configuration
openapi: 3.0.3
info:
  title: Didit Authentication API
  version: 1.0.0
  description: >-
    Didit Authentication 面向服务器的 endpoint，该产品是为您应用的终端用户提供的登录产品。Authentication
    为**新功能**，将于 2026-11-01 版本在生产环境中正式推出。


    ## 基础 URL


    每个应用都是其独立的 OpenID Connect 签发方（issuer），以下所有 endpoint 均在该签发方的根路径下提供服务：


    - 生产环境应用为 `https://<name>.auth.didit.me`，沙盒应用为
    `https://<name>.sandbox.auth.didit.me`。

    - 您的自定义域名（一旦激活）。激活后，它将取代默认主机作为签发方：新 token 会在 `iss`
    中标明该域名，发现文档（discovery）会指向它，并且可发布密钥也会改变。在默认主机下签发的 access token 将无法用于调用
    `/session/`、`/step-up/` 和 `/monitoring-token/`，直至完成刷新。


    生产环境与沙盒是独立的应用，因此它们是拥有独立密钥的不同签发方。可发布密钥为 `pk_live_`（生产环境）或
    `pk_test_`（沙盒），后接签发方去除末尾斜杠后的无填充 base64url 编码：对其解码即可找到签发方。它是一个公开标识符，并非凭据。


    相同的 JSON endpoint 也在
    `https://apx.didit.me/auth/v2/authentication/{application_id}/`
    下提供。无论由哪个地址签发，token 始终会将上述签发方声明在内。


    ## 凭据


    这些 endpoint 绝不接受您的 Didit API 密钥或控制台 token。


    - 发现文档（Discovery）、JWKS 以及 `POST /token/` 不需要任何凭据。客户端为公开客户端：不存在 client
    secret，且授权码（authorization code）与其 PKCE 验证器（`S256`）绑定。`client_id` 即为您的应用 ID。

    - `/session/`、`/step-up/` 和 `/monitoring-token/` 接收用户的 access
    token：`Authorization: Bearer
    <access_token>`。每次成功的调用均计为该会话的活动，因此会重置会话的空闲超时时间。


    ## 请求体


    所有接收请求体的 endpoint 均支持 JSON、表单编码（form-encoded）和 multipart 请求体。本文档列出了 JSON，以及
    OAuth 客户端发送 `POST /token/` 时使用的表单编码。如果 endpoint 收到不支持的字段，将返回 `400
    {"<field>": "unknown_field"}`。


    ## Token


    - **Access token**：请求头为 `typ: at+jwt` 的 ES256 JWT，有效期最多 5
    分钟，且绝不超过其会话时长。Claims 为 `AccessTokenClaims`。

    - **ID token**：请求头为 `typ: JWT` 的 ES256 JWT。Claims 为 `IDTokenClaims`。绝不能作为
    access token 使用。

    - **Refresh token**：随机字符串，每次使用时均会轮换。再次发送已使用的 refresh token 将会撤销该会话。


    使用来自 `GET /.well-known/jwks.json` 的密钥验证 token：算法必须为 `ES256`，`typ` 必须匹配 token
    类型，`iss` 必须等于您配置的签发方，且 `aud` 必须为您的应用 ID。离线验证仅在 access token
    过期后才能察觉已撤销的会话；`GET /session/` 则是即时检查手段。


    ## 错误


    | 响应体 | 适用情况 |

    | --- | --- |

    | `{"error": "<code>"}` | 来自 `POST /token/` 的错误，状态码均为 `400`，响应体格式符合 [RFC
    6749 第 5.2
    节](https://www.rfc-editor.org/rfc/rfc6749#section-5.2)：`invalid_grant`、`invalid_client`
    以及 Didit 的
    `mfa_required`。服务错误：`temporarily_unavailable`、`monitoring_unavailable`、`monitoring_disabled`。
    |

    | `{"<field>": ["<message>"]}` 或 `{"<field>": "<code>"}` |
    请求字段未通过验证。`non_field_errors` 表示跨字段规则校验失败，`unknown_field` 表示 endpoint 不接受的字段。
    |

    | `{"detail": "<message>"}` |
    `401`（`invalid_token`）、`403`（`origin_not_allowed`）、`404`（未知应用或 step-up）以及
    `429`（速率限制）。此外还包括无法解析请求体的 `400`（`JSON parse error - ...`）、endpoint 不支持该方法的
    `405` 以及不支持的 `Content-Type` 对应的 `415`。 |


    `401` 响应还会携带 `WWW-Authenticate: Bearer`，而 `429` 响应会携带以秒为单位的 `Retry-After`。


    有两种拒绝响应不是 JSON 格式。非签发方地址在到达这些 endpoint 之前就会被拒绝，例如未使用的 `*.auth.didit.me`
    名称会返回空白的 `404`。若 `step_up_id` 不是 UUID，则会返回 `404` 页面。


    ## 速率限制


    请求必须通过两层限制。


    **Endpoint 限制**，按客户端 IP 地址、应用及 endpoint 分别计数：


    - 发现文档（Discovery）与 JWKS：每分钟 1,200 次请求，每小时 12,000 次请求。

    - 其他所有 endpoint：每分钟 30 次请求，每小时 300 次请求。`GET` 和 `DELETE /session/` 共享同一个计数。


    超出限制时返回：`429 {"detail": "Too many requests from this IP address. Please wait
    before trying again. Expected available in 60 seconds."}`，小时限制则为 `3600
    seconds`。


    **Bot 防护**，适用于所有 `POST` 和 `DELETE` 请求。其桶由该应用的所有 `POST` 和 `DELETE`
    请求共享（包括托管登录步骤），并持续补充：


    - 每个客户端 IP 地址每分钟 60 次请求。

    - 每个设备每分钟 30 次请求（适用于像浏览器和原生 SDK 那样标识自身设备的请求）。

    - 整个应用（涵盖所有 IP 地址）每分钟 3,000 次请求。Token 刷新（带有 `grant_type=refresh_token` 的
    `POST /token/`）则使用独立的桶：整个应用每分钟 6,000 次。


    超出桶容量时返回：`429 {"detail": "rate_limited Expected available in N seconds."}`（当
    N 为 1 时为 `1 second.`）。基于 IP 的桶跨 endpoint 共享，因此混合调用 token、step-up
    和退出登录调用的单一地址可能会在触及任何 endpoint 限制之前就耗尽其额度。应用级别的桶会统计该应用的所有客户端，包括浏览器。


    两层限制均在 endpoint 执行前进行拦截并返回响应，因此收到 `429` 的请求并未实际执行：请在 `Retry-After`
    指定的时间之后重试（包括刷新请求）。


    ## 浏览器请求


    携带 `Origin` 请求头的请求必须来自应用自身的源或其允许的源，否则将收到 `403
    origin_not_allowed`。服务器到服务器的请求不发送 `Origin`。


    ## 此处未涵盖的内容


    以下路由用于托管页面、浏览器和原生 SDK 以及 AI agent。它们不属于服务器约定的一部分，服务器 SDK 也不会调用它们：


    - 登录步骤：`POST /authorize/`、`POST
    /password/`、`/email/*`、`/phone/*`、`/password-reset/*`、`/passkeys/*`、`/mfa/*`、`/social/*`
    和 `/protection/complete/`。

    -
    托管页面和回调：`/sign-in`、`/magic`、`/invite`、`/reset`、`/verify/`、`/sso/*`、`/wallet/callback/`、`/logo/`
    以及 `/.well-known/` 下的原生应用关联文件。

    - Agent 访问：`/agents/*` 和 `/grants/`，包括用于实时检查 AI agent 的 access token 的 `GET
    /agents/session/`。Agent 访问不属于当前版本的约定范围。

    - Authentication 的控制台管理 API（该 API 接收控制台会话）。


    Authentication 事件目前尚未作为 Webhook 投递，因此本文档未定义任何 Webhook。
servers:
  - url: https://{issuer}
    description: 您的应用的签发方：其登录来源。
    variables:
      issuer:
        default: your-app.auth.didit.me
        description: >-
          签发方主机：`<name>.auth.didit.me`（生产环境）、`<name>.sandbox.auth.didit.me`（沙盒）或您当前生效的自定义网域。
security: []
tags:
  - name: Issuer
    description: 发现和签名密钥，用于核验 token。
  - name: Tokens
    description: 授权码授予和刷新授予。
  - name: Sessions
    description: 检查并结束访问 token 背后的会话。
  - name: Step-ups
    description: 敏感操作前的验证。
  - name: Monitoring
    description: 用于交易监控事件的设备凭据。
paths:
  /.well-known/openid-configuration:
    get:
      tags:
        - Issuer
      summary: 获取 OpenID 配置
      description: >-
        签发方的发现文档：包含其 endpoint、授权类型、签名算法与声明。请从您配置的签发方处获取，切勿从 token 中发现的 URL
        获取。请按照 `Cache-Control` 的指示缓存最多 5 分钟。
      operationId: authentication_get_openid_configuration
      responses:
        '200':
          description: 发现文档。
          headers:
            Cache-Control:
              description: '`public, max-age=300`：您和共享缓存可将成功的响应保留 5 分钟，即一个访问 token 的有效期。'
              schema:
                type: string
                example: public, max-age=300
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenIDConfiguration'
              examples:
                Discovery:
                  summary: 生产环境应用
                  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: 签发方的 OpenID Connect 发现文档。请从此文档读取各 endpoint，而不是自行拼装。
      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: 签发方：应用的登录源（origin），末尾不带斜杠。每个 token 的 `iss` 都与此相同。
          example: https://your-app.auth.didit.me
        authorization_endpoint:
          type: string
          format: uri
          description: 托管登录页面（`/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`：客户端是公开的，不发送任何秘密信息。'
          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: OAuth 错误（RFC 6749 第 5.2 节）或服务错误。
      required:
        - error
      properties:
        error:
          type: string
          example: invalid_grant
  responses:
    OriginNotAllowed:
      description: 请求携带的 `Origin` 既不是该应用自身的源，也不在其允许的源列表中。服务端请求不发送 `Origin`。
      headers:
        Cache-Control:
          description: 始终为 `no-store`：切勿缓存此响应。
          schema:
            type: string
            example: no-store
        Pragma:
          description: 始终为 `no-cache`。
          schema:
            type: string
            example: no-cache
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Detail'
          examples:
            OriginNotAllowed:
              summary: 来源（Origin）不允许
              value:
                detail: origin_not_allowed
    ApplicationNotFound:
      description: >-
        该地址属于某个应用，但该应用尚未启用 Authentication 功能；在 `apx.didit.me` 地址上，应用 ID
        未知。不属于任何应用的地址在到达 endpoint 之前即被拒绝，且该响应不是 JSON 格式。
      headers:
        Cache-Control:
          description: 始终为 `no-store`：切勿缓存此响应。
          schema:
            type: string
            example: no-store
        Pragma:
          description: 始终为 `no-cache`。
          schema:
            type: string
            example: no-cache
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Detail'
          examples:
            ApplicationNotFound:
              summary: 未知应用
              value:
                detail: No Configuration matches the given query.
    RateLimited:
      description: >-
        此地址针对该 endpoint 的请求过多，或者在 `POST` 或 `DELETE` 上机器人防护令牌桶已耗尽。未执行任何操作：请等待
        `Retry-After` 秒后重试。
      headers:
        Retry-After:
          description: 重试前需要等待的秒数。
          schema:
            type: integer
            example: 60
        Cache-Control:
          description: 始终为 `no-store`：切勿缓存此响应。
          schema:
            type: string
            example: no-store
        Pragma:
          description: 始终为 `no-cache`。
          schema:
            type: string
            example: no-cache
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Detail'
          examples:
            RateLimited:
              summary: endpoint 限制
              value:
                detail: >-
                  Too many requests from this IP address. Please wait before
                  trying again. Expected available in 60 seconds.
            BotProtection:
              summary: 机器人防护限制（POST 和 DELETE）
              value:
                detail: rate_limited Expected available in 2 seconds.
    TemporarilyUnavailable:
      description: 请求所依赖的服务暂时不可用。请采用退避策略重试。
      headers:
        Cache-Control:
          description: 始终为 `no-store`：切勿缓存此响应。
          schema:
            type: string
            example: no-store
        Pragma:
          description: 始终为 `no-cache`。
          schema:
            type: string
            example: no-cache
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OAuthError'
          examples:
            TemporarilyUnavailable:
              summary: 稍后重试
              value:
                error: temporarily_unavailable

````

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