cdnca

开放接口

/v1/auth

13 个接口 · 2 个接口支持 API Key

← 全部分组 · 第一次调用？先看教程：认证、权限、请求与响应、常见失败

方法路径摘要认证
POST/v1/auth/bridge-ssoExchange a billing bridge one-time ticket for a console session无需认证
POST/v1/auth/loginAuthenticate and create a refresh-token family无需认证
POST/v1/auth/login-captchasIssue a one-time built-in sign-in CAPTCHA bound to the source address无需认证
POST/v1/auth/login-challenge-verificationsConsume one verification code and create a login session无需认证
POST/v1/auth/login-challengesQueue a login code or the additional code required after password verification无需认证
GET/v1/auth/login-methodsRead enabled email and SMS login methods无需认证
POST/v1/auth/logoutRevoke the refresh-token familyAPI Key 可调
GET/v1/auth/meReturn the current user, scope, roles, and permissions登录会话
POST/v1/auth/refreshRotate the refresh token and issue a new access tokenAPI Key 可调
POST/v1/auth/registerRegister a tenant owner account无需认证
POST/v1/auth/registration-challenge-verificationsConsume one contact verification code and issue a registration proof cookie无需认证
POST/v1/auth/registration-challengesVerify a human and queue one contact verification code无需认证
POST/v1/auth/session-region-verificationsRe-bind the session to its current region with the password登录会话

契约文件：api/openapi/v1/control.yaml api/openapi/v1/account-login-challenge.yaml api/openapi/v1/account-registration.yaml api/openapi/v1/account-registration-challenge.yaml

接口详情

POST /v1/auth/bridge-sso

Exchange a billing bridge one-time ticket for a console session

operationId
exchangeBillingBridgeSso
认证
  • 无需认证。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Called by the console page /sso/bridge?ticket=… without Authorization (the ticket is the credential). Signs the customer in with an ordinary session of its own (not impersonation; audit auth.login with authentication_method billing_bridge and auth.session.bridge_sso). Expired, reused, unknown, disabled-user and terminated-service tickets are all 401 bridge_sso_invalid. The account's e-mail/SMS login verification is skipped; when the plugin setting sso_require_mfa is on and the customer has TOTP, the first call is 401 mfa_required and the same ticket is sent again with authentication (mfa_invalid_code, mfa_code_replayed on a wrong code; five wrong codes void the ticket).

请求体

application/json · 必填：是

exchangeBillingBridgeSso 请求体
名称类型必填说明
ticketstring是—
authenticationobject否—

响应

exchangeBillingBridgeSso 响应
状态码说明
200Signed in. The refresh token is set only as an HttpOnly cookie.

字段：access_token: string token_type: string expires_in: integer(int64) principal: Principal impersonation?: ImpersonationMarker redirect: string

400请求体或参数不合法。
401bridge_sso_invalid, mfa_required, mfa_invalid_code or mfa_code_replayed.
403当前身份没有执行该操作的权限。
503A required dependency is unavailable.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/auth/login

Authenticate and create a refresh-token family

operationId
login
认证
  • 无需认证。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

login 参数
名称位置类型必填说明
Idempotency-Keyheaderstring否Required when login_challenge is present. Reuse only for the same challenge and code.

请求体

application/json · 必填：是

login 请求体
名称类型必填说明
usernamestring是—
passwordstring(password)是—
scope_idstring(uuid)否Optional active platform or tenant scope. Platform is preferred when omitted.
login_challengeobject否Additional email/SMS proof. Password, current policy, source, contact and code are rechecked when creating the session in the same transaction.
captchaLoginCaptchaAnswer否Solved built-in sign-in CAPTCHA (POST /v1/auth/login-captchas). Case-insensitive.

响应

login 响应
状态码说明
200Authenticated. The rotating refresh token is returned only as an HttpOnly cookie.

字段：access_token: string token_type: string expires_in: integer(int64) principal: Principal impersonation?: ImpersonationMarker

400请求体或参数不合法。
401Invalid credentials, login_verification_required after a correct password, login_captcha_required once the platform CAPTCHA threshold (login_captcha_threshold_per_hour) is reached for this account and source, or login_captcha_invalid. No session is created until the required code succeeds.
403当前身份没有执行该操作的权限。
409请求的状态与已有资源或幂等记录冲突。
429login_throttled. The account has login_failure_limit_per_hour credential failures from this source in the last hour (or the source has five times that across accounts). Another source is not affected. Retry after the Retry-After seconds.
503A required dependency is unavailable.
500服务内部故障，请求未完成。

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 429 被限速：等待后再试，降低并发。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/auth/login-captchas

Issue a one-time built-in sign-in CAPTCHA bound to the source address

operationId
issueLoginCaptcha
认证
  • 无需认证。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Requested after login_captcha_required. The answer is never returned as text; send {id, answer} as captcha with the next password attempt. Each challenge is consumed by one attempt and expires after five minutes. Thirty challenges per source per hour.

响应

issueLoginCaptcha 响应
状态码说明
201CAPTCHA issued.

字段：id: string(uuid) image: string expires_at: string(date-time)

429login_captcha_rate_limited.
503A required dependency is unavailable.

失败时怎么办

  • 429 被限速：等待后再试，降低并发。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/auth/login-challenge-verifications

Consume one verification code and create a login session

operationId
verifyAccountLoginChallenge
认证
  • 无需认证。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

The code and session are committed in the same transaction after the current source policy and bound contact are checked. Accounts requiring password plus a code must finish through /v1/auth/login instead; this endpoint cannot bypass that requirement and returns account_login_verification_invalid.

参数

verifyAccountLoginChallenge 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是—
X-Request-IDheaderstring是—

请求体

application/json · 必填：是

verifyAccountLoginChallenge 请求体
名称类型必填说明
challenge_idstring(uuid)是—
identifierstring是—
channelstring: email / sms是—
otpstring是—

响应

verifyAccountLoginChallenge 响应
状态码说明
200Authenticated. The rotating refresh token is returned only as an HttpOnly cookie and the one-time challenge is consumed.

字段：access_token: string token_type: string expires_in: integer(int64) principal: Principal

401Stable error without provider details or sensitive input.
403Stable error without provider details or sensitive input.
409Stable error without provider details or sensitive input.
422Stable error without provider details or sensitive input.
503Stable error without provider details or sensitive input.

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/auth/login-challenges

Queue a login code or the additional code required after password verification

operationId
createAccountLoginChallenge
认证
  • 无需认证。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

createAccountLoginChallenge 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是—
X-Request-IDheaderstring是—

请求体

application/json · 必填：是

响应

createAccountLoginChallenge 响应
状态码说明
202Challenge accepted without identifying whether the account exists.

字段：data: object

401Stable error without provider details or sensitive input.
403Stable error without provider details or sensitive input.
409Stable error without provider details or sensitive input.
422Stable error without provider details or sensitive input.
429Bounded retry response without identifying the limiting dimension.
503Stable error without provider details or sensitive input.

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 429 被限速：等待后再试，降低并发。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/auth/login-methods

Read enabled email and SMS login methods

operationId
getAccountLoginMethods
认证
  • 无需认证。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

响应

getAccountLoginMethods 响应
状态码说明
200Public login method policy for the resolved platform scope.

字段：data: object

422Stable error without provider details or sensitive input.
503Stable error without provider details or sensitive input.

失败时怎么办

  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/auth/logout

Revoke the refresh-token family

operationId
logout
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

When the request still carries the cdnca_impersonation cookie, the impersonation it identifies is revoked first (reason logout), so the cookie is refused immediately instead of at its expiry.

响应

logout 响应
状态码说明
204The family is revoked or the cookie was already absent.
500服务内部故障，请求未完成。

失败时怎么办

  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/auth/me

Return the current user, scope, roles, and permissions

operationId
getCurrentIdentity
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Requires the server-side identity.self.read permission in the active scope.

参数

getCurrentIdentity 参数
名称位置类型必填说明
limitqueryinteger否—
statusquerystring: pending_activation / active / revoked否—
namequerystring否—
key_idquerystring否—
cursorquerystring否—

响应

getCurrentIdentity 响应
状态码说明
200Current identity and effective RBAC grants. An active impersonation cookie returns the target principal with a non-sensitive impersonation marker.

字段：user_id: string(uuid) display_id: string scope_id: string(uuid) scope_kind: string: platform / tenant tenant_id?: string(uuid) | null(uuid) username: string display_name: string roles: array<string> permissions: array<string> password_change_required?: boolean impersonation?: ImpersonationMarker

401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
500服务内部故障，请求未完成。

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/auth/refresh

Rotate the refresh token and issue a new access token

operationId
refresh
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

响应

refresh 响应
状态码说明
200Rotated. An active impersonation cookie returns the target principal and a non-sensitive impersonation marker. Reusing the previous refresh cookie revokes the complete token family.

字段：access_token: string token_type: string expires_in: integer(int64) principal: Principal impersonation?: ImpersonationMarker

401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
500服务内部故障，请求未完成。

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/auth/register

Register a tenant owner account

operationId
registerAccount
认证
  • 无需认证。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Requires exact application/json, one Idempotency-Key, and one trusted X-Request-ID. JSON is size bounded and rejects duplicate keys, unknown fields, media-type parameters, trailing values, and query parameters. The configured current terms version must be accepted. A 202 response never reports whether username, email, or phone already existed.

参数

registerAccount 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是Stable key for the normalized registration and server-verified proof. Reusing it with a different payload or proof evidence returns 409.
X-Request-IDheaderstring是Trusted request identifier for receipt and audit correlation.

请求体

application/json · 必填：是

registerAccount 请求体
名称类型必填说明
usernamestring是—
passwordstring(password)是8 to 1024 printable ASCII characters (no space) with at least two of upper case, lower case, digits and symbols; otherwise password_policy_unmet.
display_namestring是—
emailstring(email)是—
phonestring是—
terms_acceptedboolean是—
terms_versionstring是—
verification_channelstring: email / sms是—

响应

registerAccount 响应
状态码说明
202Uniform registration acceptance or exact idempotent replay.

字段：accepted: boolean replayed: boolean

409Stable error without raw service messages or sensitive input.
422Stable error without raw service messages or sensitive input.
429Rate limit response without identifying the limiting dimension.
503Stable error without raw service messages or sensitive input.

失败时怎么办

  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 429 被限速：等待后再试，降低并发。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/auth/registration-challenge-verifications

Consume one contact verification code and issue a registration proof cookie

operationId
verifyAccountRegistrationChallenge
认证
  • 无需认证。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

verifyAccountRegistrationChallenge 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是—
X-Request-IDheaderstring是—

请求体

application/json · 必填：是

verifyAccountRegistrationChallenge 请求体
名称类型必填说明
challenge_idstring(uuid)是—
usernamestring是—
emailstring(email)是—
phonestring是—
verification_channelstring: email / sms是—
otpstring是—

响应

verifyAccountRegistrationChallenge 响应
状态码说明
204Contact verified. The proof reference is available only in a secure host cookie.
409Stable error without provider details or sensitive input.
422Stable error without provider details or sensitive input.
429Bounded retry response without identifying the limiting dimension.
503Stable error without provider details or sensitive input.

失败时怎么办

  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 429 被限速：等待后再试，降低并发。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/auth/registration-challenges

Verify a human and queue one contact verification code

operationId
createAccountRegistrationChallenge
认证
  • 无需认证。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

createAccountRegistrationChallenge 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是—
X-Request-IDheaderstring是—

请求体

application/json · 必填：是

createAccountRegistrationChallenge 请求体
名称类型必填说明
usernamestring是—
emailstring(email)是—
phonestring是—
verification_channelstring: email / sms是—
human_tokenstring是—

响应

createAccountRegistrationChallenge 响应
状态码说明
202Challenge accepted without identifying existing accounts.

字段：data: object

409Stable error without provider details or sensitive input.
422Stable error without provider details or sensitive input.
429Bounded retry response without identifying the limiting dimension.
503Stable error without provider details or sensitive input.

失败时怎么办

  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 429 被限速：等待后再试，降低并发。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/auth/session-region-verifications

Re-bind the session to its current region with the password

operationId
verifySessionRegion
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Called after a session request returned 401 session_region_changed (platform setting session_region_check). The password attempt is throttled like sign-in.

请求体

application/json · 必填：是

verifySessionRegion 请求体
名称类型必填说明
passwordstring是—

响应

verifySessionRegion 响应
状态码说明
204Session re-bound to the current region.
400请求体或参数不合法。
401invalid_session or invalid_credentials.
429login_throttled.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 429 被限速：等待后再试，降低并发。

↑ 回到列表