Operation details
POST /v1/auth/bridge-sso
Exchange a billing bridge one-time ticket for a console session
- operationId
exchangeBillingBridgeSso- Auth
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
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).
Request body
application/json · Required：Yes
exchangeBillingBridgeSso Request body| Name | Type | Required | Description |
|---|
ticket | string | Yes | — |
|---|
authentication | object | No | — |
|---|
Responses
exchangeBillingBridgeSso Responses| Status | Description |
|---|
200 | Signed in. The refresh token is set only as an HttpOnly cookie. Fields：access_token: string token_type: string expires_in: integer(int64) principal: Principal impersonation?: ImpersonationMarker redirect: string |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | bridge_sso_invalid, mfa_required, mfa_invalid_code or mfa_code_replayed. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
503 | A required dependency is unavailable. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/auth/login
Authenticate and create a refresh-token family
- operationId
login- Auth
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
login Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | No | Required when login_challenge is present. Reuse only for the same challenge and code. |
|---|
Request body
application/json · Required：Yes
login Request body| Name | Type | Required | Description |
|---|
username | string | Yes | — |
|---|
password | string(password) | Yes | — |
|---|
scope_id | string(uuid) | No | Optional active platform or tenant scope. Platform is preferred when omitted. |
|---|
login_challenge | object | No | Additional email/SMS proof. Password, current policy, source, contact and code are rechecked when creating the session in the same transaction. |
|---|
captcha | LoginCaptchaAnswer | No | Solved built-in sign-in CAPTCHA (POST /v1/auth/login-captchas). Case-insensitive. |
|---|
Responses
login Responses| Status | Description |
|---|
200 | Authenticated. The rotating refresh token is returned only as an HttpOnly cookie. Fields：access_token: string token_type: string expires_in: integer(int64) principal: Principal impersonation?: ImpersonationMarker |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Invalid 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 | The authenticated principal is not allowed to perform the action. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
429 | login_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. |
|---|
503 | A required dependency is unavailable. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.429 Rate limited: wait, then retry with lower concurrency.503 A dependency is unavailable: retry later with the original Idempotency-Key.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
POST /v1/auth/login-captchas
Issue a one-time built-in sign-in CAPTCHA bound to the source address
- operationId
issueLoginCaptcha- Auth
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
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.
Responses
issueLoginCaptcha Responses| Status | Description |
|---|
201 | CAPTCHA issued. Fields：id: string(uuid) image: string expires_at: string(date-time) |
|---|
429 | login_captcha_rate_limited. |
|---|
503 | A required dependency is unavailable. |
|---|
What to do on failure
429 Rate limited: wait, then retry with lower concurrency.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/auth/login-challenge-verifications
Consume one verification code and create a login session
- operationId
verifyAccountLoginChallenge- Auth
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
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.
Parameters
verifyAccountLoginChallenge Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
verifyAccountLoginChallenge Request body| Name | Type | Required | Description |
|---|
challenge_id | string(uuid) | Yes | — |
|---|
identifier | string | Yes | — |
|---|
channel | string: email / sms | Yes | — |
|---|
otp | string | Yes | — |
|---|
Responses
verifyAccountLoginChallenge Responses| Status | Description |
|---|
200 | Authenticated. The rotating refresh token is returned only as an HttpOnly cookie and the one-time challenge is consumed. Fields：access_token: string token_type: string expires_in: integer(int64) principal: Principal |
|---|
401 | Stable error without provider details or sensitive input. |
|---|
403 | Stable error without provider details or sensitive input. |
|---|
409 | Stable error without provider details or sensitive input. |
|---|
422 | Stable error without provider details or sensitive input. |
|---|
503 | Stable error without provider details or sensitive input. |
|---|
What to do on failure
401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/auth/login-challenges
Queue a login code or the additional code required after password verification
- operationId
createAccountLoginChallenge- Auth
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
createAccountLoginChallenge Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
Responses
createAccountLoginChallenge Responses| Status | Description |
|---|
202 | Challenge accepted without identifying whether the account exists. Fields：data: object |
|---|
401 | Stable error without provider details or sensitive input. |
|---|
403 | Stable error without provider details or sensitive input. |
|---|
409 | Stable error without provider details or sensitive input. |
|---|
422 | Stable error without provider details or sensitive input. |
|---|
429 | Bounded retry response without identifying the limiting dimension. |
|---|
503 | Stable error without provider details or sensitive input. |
|---|
What to do on failure
401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.429 Rate limited: wait, then retry with lower concurrency.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/auth/login-methods
Read enabled email and SMS login methods
- operationId
getAccountLoginMethods- Auth
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Responses
getAccountLoginMethods Responses| Status | Description |
|---|
200 | Public login method policy for the resolved platform scope. Fields：data: object |
|---|
422 | Stable error without provider details or sensitive input. |
|---|
503 | Stable error without provider details or sensitive input. |
|---|
What to do on failure
503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/auth/logout
Revoke the refresh-token family
- operationId
logout- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
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.
Responses
logout Responses| Status | Description |
|---|
204 | The family is revoked or the cookie was already absent. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
GET /v1/auth/me
Return the current user, scope, roles, and permissions
- operationId
getCurrentIdentity- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires the server-side identity.self.read permission in the active scope.
Parameters
getCurrentIdentity Parameters| Name | In | Type | Required | Description |
|---|
limit | query | integer | No | — |
|---|
status | query | string: pending_activation / active / revoked | No | — |
|---|
name | query | string | No | — |
|---|
key_id | query | string | No | — |
|---|
cursor | query | string | No | — |
|---|
Responses
getCurrentIdentity Responses| Status | Description |
|---|
200 | Current identity and effective RBAC grants. An active impersonation cookie returns the target principal with a non-sensitive impersonation marker. Fields：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 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
POST /v1/auth/refresh
Rotate the refresh token and issue a new access token
- operationId
refresh- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Responses
refresh Responses| Status | Description |
|---|
200 | Rotated. An active impersonation cookie returns the target principal and a non-sensitive impersonation marker. Reusing the previous refresh cookie revokes the complete token family. Fields：access_token: string token_type: string expires_in: integer(int64) principal: Principal impersonation?: ImpersonationMarker |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
POST /v1/auth/register
Register a tenant owner account
- operationId
registerAccount- Auth
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
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.
Parameters
registerAccount Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | Stable key for the normalized registration and server-verified proof. Reusing it with a different payload or proof evidence returns 409. |
|---|
X-Request-ID | header | string | Yes | Trusted request identifier for receipt and audit correlation. |
|---|
Request body
application/json · Required：Yes
registerAccount Request body| Name | Type | Required | Description |
|---|
username | string | Yes | — |
|---|
password | string(password) | Yes | 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_name | string | Yes | — |
|---|
email | string(email) | Yes | — |
|---|
phone | string | Yes | — |
|---|
terms_accepted | boolean | Yes | — |
|---|
terms_version | string | Yes | — |
|---|
verification_channel | string: email / sms | Yes | — |
|---|
Responses
registerAccount Responses| Status | Description |
|---|
202 | Uniform registration acceptance or exact idempotent replay. Fields：accepted: boolean replayed: boolean |
|---|
409 | Stable error without raw service messages or sensitive input. |
|---|
422 | Stable error without raw service messages or sensitive input. |
|---|
429 | Rate limit response without identifying the limiting dimension. |
|---|
503 | Stable error without raw service messages or sensitive input. |
|---|
What to do on failure
409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.429 Rate limited: wait, then retry with lower concurrency.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/auth/registration-challenge-verifications
Consume one contact verification code and issue a registration proof cookie
- operationId
verifyAccountRegistrationChallenge- Auth
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
verifyAccountRegistrationChallenge Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
verifyAccountRegistrationChallenge Request body| Name | Type | Required | Description |
|---|
challenge_id | string(uuid) | Yes | — |
|---|
username | string | Yes | — |
|---|
email | string(email) | Yes | — |
|---|
phone | string | Yes | — |
|---|
verification_channel | string: email / sms | Yes | — |
|---|
otp | string | Yes | — |
|---|
Responses
verifyAccountRegistrationChallenge Responses| Status | Description |
|---|
204 | Contact verified. The proof reference is available only in a secure host cookie. |
|---|
409 | Stable error without provider details or sensitive input. |
|---|
422 | Stable error without provider details or sensitive input. |
|---|
429 | Bounded retry response without identifying the limiting dimension. |
|---|
503 | Stable error without provider details or sensitive input. |
|---|
What to do on failure
409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.429 Rate limited: wait, then retry with lower concurrency.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/auth/registration-challenges
Verify a human and queue one contact verification code
- operationId
createAccountRegistrationChallenge- Auth
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
createAccountRegistrationChallenge Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
createAccountRegistrationChallenge Request body| Name | Type | Required | Description |
|---|
username | string | Yes | — |
|---|
email | string(email) | Yes | — |
|---|
phone | string | Yes | — |
|---|
verification_channel | string: email / sms | Yes | — |
|---|
human_token | string | Yes | — |
|---|
Responses
createAccountRegistrationChallenge Responses| Status | Description |
|---|
202 | Challenge accepted without identifying existing accounts. Fields：data: object |
|---|
409 | Stable error without provider details or sensitive input. |
|---|
422 | Stable error without provider details or sensitive input. |
|---|
429 | Bounded retry response without identifying the limiting dimension. |
|---|
503 | Stable error without provider details or sensitive input. |
|---|
What to do on failure
409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.429 Rate limited: wait, then retry with lower concurrency.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/auth/session-region-verifications
Re-bind the session to its current region with the password
- operationId
verifySessionRegion- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Called after a session request returned 401 session_region_changed (platform setting session_region_check). The password attempt is throttled like sign-in.
Request body
application/json · Required：Yes
verifySessionRegion Request body| Name | Type | Required | Description |
|---|
password | string | Yes | — |
|---|
Responses
verifySessionRegion Responses| Status | Description |
|---|
204 | Session re-bound to the current region. |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | invalid_session or invalid_credentials. |
|---|
429 | login_throttled. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.429 Rate limited: wait, then retry with lower concurrency.
↑ Back to list