API referenceidentity
Send activation terms code
POST
/v1/activation/terms:send-codeIdempotency-Key requiredAccepts bearer
E-mail the signed-in Owner a code to accept the terms with — CAPPED flow only
Sends a 6-digit code to the signed-in Owner's own e-mail address (the address they signed in with; never one taken from the request) so the Owner can accept the terms without an authenticator app:…Show more
Sends a 6-digit code to the signed-in Owner's own e-mail address (the address they signed in with; never one taken from the request) so the Owner can accept the terms without an authenticator app: POST /v1/activation/terms:accept with emailCode. A new sign-up has no second factor, so on the CAPPED flow this is the step-up of the terms step. The code lives 15 minutes and allows at most 5 attempts, as the sign-up code; sending a new code voids the previous one. sentTo is the address masked (the first two characters of the local part, or the first one when it is shorter than three, then *** and the domain); expiresAt is when the code stops working; resendAfter is the earliest time another code may be sent (60 seconds after this one). Served on the CAPPED flow only: a tenant whose GET /v1/activation flow is NINE_STEP is 409 CONFLICT details.reason FLOW_NOT_CAPPED (step up with stepUpCode or stepUpAssertion there). Rate limited per Owner as the identity code routes are (IdentityRateLimited): a send before resendAfter, or more than 5 sends in a 15-minute window, is 429 RATE_LIMITED details.reason SUBJECT_RATE_LIMITED, details.action terms-code-send, with Retry-After and details.retryAfterMs; nothing is sent. No request body (an empty JSON object is accepted and ignored). Human session only (an API key or a service token is 403 PERMISSION_DENIED details.reason SESSION_REQUIRED); Owner only. Idempotency-Key required: a replay answers the first 202 and sends nothing. Identity mail goes through SMTP; a deployment without a sender is 501 NOT_IMPLEMENTED details.reason NO_VERIFICATION_SENDER. The code is never logged, audited or returned. Audited (activation.terms_code_sent, with sentTo masked). no longer used by the console on the CAPPED flow — the terms are accepted there with termsVersion only (click-wrap, POST /v1/activation/terms:accept); kept for compatibility, and an emailCode it sent is still judged by terms:accept.Headers
- Idempotency-KeystringRequired
Mandatory on mutations: **48h TTL**; replay with same body-hash returns the original response with Idempotency-Replayed true; same key + different body is 409 IDEMPOTENCY_CONFLICT; in-flight duplicate…Show more
Mandatory on mutations: **48h TTL**; replay with same body-hash returns the original response with Idempotency-Replayed true; same key + different body is 409 IDEMPOTENCY_CONFLICT; in-flight duplicate is 409 IDEMPOTENCY_IN_PROGRESS.
Request body
This operation takes no request body.
Responses
- 202Accepted — a code is on its way to the signed-in Owner's e-mail addressTermsCodeSent
- 401ApiErrorResponse
UNAUTHENTICATED — missing or expired token.Show more
UNAUTHENTICATED — missing or expired token. Declared on every operation because `security` is declared globally at the document root: every route is authenticated, so every route can answer 401. - 403ApiErrorResponse
- 405ApiErrorResponse
VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge).Show more
VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge). Not retryable as sent. - 409CONFLICT FLOW_NOT_CAPPED — the tenant is on the nine-step rail; or IDEMPOTENCY_CONFLICTApiErrorResponse
- 414ApiErrorResponse
VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge).Show more
VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge). Not retryable as sent: send long input in the body of a POST. - 429RATE_LIMITED SUBJECT_RATE_LIMITED (action terms-code-send) — too soon after the last code, or too many codesApiErrorResponse
- 500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse
- 501Not retryable.ApiErrorResponse
Errors you should handle
Branch on code and honour retryable — never on the HTTP status alone.
| 401 | UNAUTHENTICATED The bearer token is expired. Re-authenticate and retry. | not retryable |
| 403 | PERMISSION_DENIED Reading wallets needs the finance:read permission. | not retryable |
| 405 | VALIDATION This method is not served. | not retryable |
| 409 | CONFLICT This tenant is on the nine-step activation. Accept the terms with your authenticator code or passkey. | not retryable |
| 409 | IDEMPOTENCY_CONFLICT Idempotency-Key 7f0c33d1-9a1e-4d2c-9f77-1c0f2b3a4d55 was used with a different body; never executed | not retryable |
| 414 | VALIDATION The request URI is longer than 8 KiB. | not retryable |
| 429 | RATE_LIMITED A code was sent a moment ago. Wait for the Retry-After interval before asking for another. | retryable |
| 500 | INTERNAL An unexpected error occurred. Quote the traceId to support. | retryable |
| 501 | NOT_IMPLEMENTED The capped activation flow is not available on this deployment. | not retryable |