跳到主要内容
Sursa Developers

POST/oauth/token

签发 OAuth 2.0 令牌

oauth_token

OAuth 2.0 令牌端点（RFC 6749，第 3.2 节）。grant_type：authorization_code 用一次性授权码换取一对令牌，需要 code_verifier（PKCE S256）；refresh_token 用刷新令牌换取新的一对令牌，并使之前的刷新令牌失效（轮换），重复使用已失效的刷新令牌会撤销整条令牌链；client_credentials 以组织的名义签发令牌，仅适用于 confidential 应用，不签发刷新令牌。confidential 客户端通过 Authorization: Basic 头或 client_id 和 client_secret 字段进行身份验证；公共客户端只发送 client_id。访问令牌有效期为 1 小时，刷新令牌为 90 天。响应和错误遵循 RFC 6749 第 5 节，并带有 Cache-Control: no-store。在 1.62.0 中新增。

身份验证

无需凭据。

请求体

application/x-www-form-urlencoded

对象：OAuthTokenRequest

  • grant_typestring必填

    可选值: authorization_coderefresh_tokenclient_credentials

  • codestring

    授权码（authorization_code）。

  • redirect_uristring

    与授权请求中相同的重定向 URI（authorization_code）。

  • code_verifierstring

    原始的 PKCE 值，43 到 128 个字符（authorization_code）。

  • refresh_tokenstring

    刷新令牌（refresh_token）。

  • scopestring

    以空格分隔的权限范围，只能缩小（refresh_token、client_credentials）。

  • client_idstring

    应用 ID，用于未在 Authorization: Basic 头中传递密钥的情况。

  • client_secretstring

    confidential 应用的客户端密钥，用于未在 Authorization: Basic 头中传递的情况。

响应

200已签发令牌。

响应头

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：OAuthTokenResponse

  • access_tokenstring必填

    用于 Authorization: Bearer 头的访问令牌（kbat_…）。

  • token_typestring必填

    可选值: Bearer

  • expires_ininteger必填

    访问令牌的有效期（秒）。

  • refresh_tokenstring

    刷新令牌（kbrt_…）；客户端凭据方式不返回。

  • scopestring必填

    令牌的权限范围，以空格分隔。

400RFC 6749 第 5.2 节定义的错误。

响应头

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：OAuthErrorResponse

401客户端凭据无效（`invalid_client`）。

响应头

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：OAuthErrorResponse

安全重试

每个 POST 和 PATCH 请求都传入 Idempotency-Key 头（例如一个 UUID）。24 小时内用同一个键重试时，返回已保存的响应，不会再次执行请求。

速率限制

响应带有 RateLimit 和 RateLimit-Policy 头，以及旧版的 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 头。429 响应带有以秒为单位的 Retry-After：等待后重试。

← oauth · API 参考