Issue a claim token
Issues a single-use claim_token, and the claim_url built from it, so the account's holder can set a password and take ownership.
- email: send it when the account has no holder yet — the person is created by this call. Omit the body to re-issue the token for the holder the account already has. An email that differs from the existing holder's is rejected rather than replacing them.
- Lifetime: tokens last 30 days, and only the last one issued is live. Issuing again invalidates the previous token, so the old link stops working the moment you ask for a new one.
- Not an invitation: this hands the account itself over to its holder. To add a further person to an account that already has one, invite them with POST /v1/accounts/{account_id}/invitations.
- Entitlement: requires manage_accounts.
Request
- Base URL: https://app.beel.es/api
- URL: https://app.beel.es/api/v1/accounts/{account_id}/claim-tokens
- Auth: HTTP bearer
Path parameters
Identifier (UUID) of an account you provisioned. An account you did not provision answers exactly like one that does not exist, so its existence is never disclosed.
Headers
Idempotency key to prevent duplicates in sensitive operations.
- Any unique client-generated string (e.g. an order id). A UUID also works but is not required
- Allowed characters: letters, digits, _ and - (max 255 chars)
- Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
- A 4xx is not stored: the key is released, so the corrected request can reuse it
- Stored responses expire 24 hours after processing
The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.
| Status | Code | When |
|---|---|---|
| 400 | INVALID_IDEMPOTENCY_KEY | The key breaks the format rules above. |
| 409 | IDEMPOTENCY_KEY_PROCESSING | The first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key. |
| 409 | IDEMPOTENCY_KEY_MISMATCH | The key was already used with a different body. Use a new key. |
Request body
Example request
{
"language": "es"
}Response
Token issued. Any previously issued token for this account is now invalid. Send an Idempotency-Key header to get the same token back on a retry instead of a fresh one.
Example response
{
"success": true,
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}Changes
No recorded changes to this operation across all 1 revision of this API.