--- title: "Claim or change the organization handle" method: PUT path: "/account/organization-handle" tags: ["account"] --- # Claim or change the organization handle `PUT /account/organization-handle` ## Request - Base URL: `https://api.sparkvault.com/v1` - URL: `https://api.sparkvault.com/v1/account/organization-handle` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Claim the organization's handle, or change it. Its sign-in page then answers at https://auth.sv/{handle}, beside the base62 address of the account id, which keeps working. A change commits only against the impacts the server computes: send `impacts_acknowledged` empty, and a change answers 409 IMPACTS_CHANGED with `details.impacts`, the addresses it moves, and `details.impacts_acknowledged`, their acknowledgements; confirm by sending those acknowledgements back as listed. An acknowledgement names one impact whole (its kind and both addresses), so a confirm made before another change landed is refused again with the impacts the change has now. A first claim moves no address and commits at once. The old handle stays the organization's for good: its address redirects to the current one, and no one can claim it again, the organization included. An organization keeps at most 3 former handles: past them, the 409 also lists in `details.tombstone_candidates` the former handles the change may give up (those it left at least 30 days ago), and the confirm names one as `tombstone_handle`. A given-up handle stays the organization's, never claimable again, and stops redirecting. An organization claims or changes a handle only while it holds a product the handle serves (Secure Identity, the help desk or Notify), and changes it at most 3 times in 30 days; a first claim is no change. A request for the handle the organization already holds changes nothing. Each claim spends one of the account's 60 hourly handle checks. Org admins only, from an interactive session. ## Request body - object - `handle` string, required: An organization handle: three to 40 lowercase letters, digits and single hyphens, starting with a letter and ending with a letter or digit. - `impacts_acknowledged` string[], required: The impacts the admin confirmed: empty for a first claim, and for a change the acknowledgements a 409 IMPACTS_CHANGED answer listed in `details.impacts_acknowledged`, sent back as listed. - `tombstone_handle` string: The former handle a change gives up, sent only when the organization already keeps the most former handles it can: one of the `details.tombstone_candidates` a 409 IMPACTS_CHANGED or HANDLE_TOMBSTONE_REQUIRED answer listed. ## Response `200` The handle the organization now holds, and the addresses the change moved. - object - `data` OrganizationHandleClaimed, required: The handle the organization holds after the request, and what the request moved. - `organization_handle` string, required - `impacts` OrganizationHandleImpact[], required: Empty for a first claim. - `kind` 'auth_host' | 'help_desk_host' | 'help_desk_email_domain' | 'notify_email_domain', required: auth_host: the hosted sign-in page. help_desk_host: the help desk's address, while the desk is active. help_desk_email_domain: the help desk's mail domain under the handle, while the desk is active and its email goes out or comes back under it (a custom domain that both sends and receives keeps the desk's email where it is). notify_email_domain: Notify's mail domain under the handle, while the organization's Notify email goes out under it (a custom domain Notify sends from keeps its email where it is). - `from` string, required: The address before the change. - `to` string, required: The address after it. - `meta` ResponseMeta: Envelope metadata present on every successful response. - `api_version` string - `request_id` string - `response_ms` integer - `timestamp` integer: Unix seconds. - `pools` object: Storage and bandwidth capacity snapshot for the account. - `billing` object - `past_due` boolean - `quota` object: This minute of the account request budget. Present on authenticated success responses that passed the throttle; absent otherwise. - `limit` integer - `used` integer - `remaining` integer - `resets_at` integer: Unix seconds. ## Other responses - `400`: VALIDATION_ERROR — the handle is outside the grammar or reserved, a handle that reads as SparkVault's brand included (`details.reason` invalid | reserved), `tombstone_handle` names a former handle on a change that gives up none (`details.field` tombstone_handle), or the body is malformed. - `401`: AUTHENTICATION_ERROR — missing or invalid credentials. - `403`: FORBIDDEN — the caller is not an org admin, or the credential is an API key. HANDLE_REQUIRES_PRODUCT — the organization holds no product the handle serves (`details.products`). - `409`: IMPACTS_CHANGED — `impacts_acknowledged` is not exactly the acknowledgements of the impacts the change has; `details.impacts` lists the impacts, `details.impacts_acknowledged` their acknowledgements and `details.tombstone_candidates` the former handles the change may give up (empty when it gives up none). HANDLE_TOMBSTONE_REQUIRED — the change gives a former handle up and `tombstone_handle` names none of `details.tombstone_candidates`, with the same details. HANDLE_TAKEN — another claim holds the handle. CONFLICT — the organization's handle changed while the request ran; read it again and retry. - `429`: RATE_LIMIT_EXCEEDED — the account has spent its 60 handle checks this hour. HANDLE_CHANGE_LIMIT — the organization has changed its handle 3 times in the last 30 days. `Retry-After` carries the seconds until the budget reopens or the change is allowed, and `details.resets_at` the moment. ## Changes - **2026-10-28** `a9a10e328ba5`: 20 info - the response property `error/details` became required for the status `400` - the response property `error/details` became required for the status `401` - the response property `error/details` became required for the status `403` - the response property `error/details` became required for the status `409` - …16 more - **2026-10-28** `56d7c265a77a`: 5 breaking, 2 warning, 1 info - the response property `error/details` became nullable for the status `400` - the response property `error/details` became nullable for the status `401` - the response property `error/details` became nullable for the status `403` - the response property `error/details` became nullable for the status `409` - …4 more - **2026-10-22** `f5ac9c809ef7`: 2 warning - added the new `email_domain` enum value to the `data/impacts/items/kind` response property for the response status `200` - added the new `help_desk_host` enum value to the `data/impacts/items/kind` response property for the response status `200` - **2026-10-21** `9f5e902abd83`: 1 info - endpoint added [Operation history](https://skmtc.dev/sparkvault/apis/sparkvault-api/changes/account/organization-handle/put.md) --- [API](https://skmtc.dev/sparkvault/apis/sparkvault-api.md) - [All operations](https://skmtc.dev/sparkvault/apis/sparkvault-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sparkvault/apis/sparkvault-api/revisions/97cfadccd0c0?raw)