Bot account onboarding

Content reviewed 2026-10-04 · Maintained by Cleo Powered · Report a documentation issue · Verification basis

Muse and similar bots can connect a new user without asking for a password or taking payment in chat. The bot needs HTTP tools and private credential storage; this is a custom integration, not a native Muse partnership.

Account fields

Field: name
Requirement: Required; the user's name.
Field: email
Requirement: Required; used for password setup and account recovery. No email-verification gate.
Field: phone_number
Requirement: Required; a valid US phone in E.164, verified by SMS.
Field: organization
Requirement: Optional; omit, null, or blank to use the person's name.
Field: client_name
Requirement: Optional; identify this connection, such as Muse.
Field: acceptable_use_accepted
Requirement: Required true after explicit responsible-use consent and agreement to the verification text.

Field	Requirement
name	Required; the user's name.
email	Required; used for password setup and account recovery. No email-verification gate.
phone_number	Required; a valid US phone in E.164, verified by SMS.
organization	Optional; omit, null, or blank to use the person's name.
client_name	Optional; identify this connection, such as Muse.
acceptable_use_accepted	Required true after explicit responsible-use consent and agreement to the verification text.

Register, verify, connect

Collect the fields and consent. Generate 32 random bytes as a 43-character base64url signup nonce; keep it secret.
POST /v1/onboarding/start with the signup JSON and that nonce in Idempotency-Key. Save onboarding_token and phone.challenge_id. An identical retry does not send another SMS.
Ask for the user's six-digit SMS code. Send challenge_id and code to POST /v1/onboarding/verify using Authorization: Bearer <ONBOARDING_TOKEN>. Use /v1/onboarding/resend only at the user's request and after the cooldown.
When verified is true, POST /v1/onboarding/complete with that onboarding bearer and no body. Securely store the returned api_key for this user, workspace, and project. An issuance retry returns the same active key.
Cleo requests an email with a single-use password-setup link. The user creates their dashboard password there, not in the bot. Calling does not wait for password setup. Discard onboarding credentials after safely storing the calling key.

Signup JSON

{
  "name": "Mina Patel",
  "email": "mina@example.com",
  "phone_number": "+12015550123",
  "client_name": "Muse",
  "acceptable_use_accepted": true
}

Two different kinds of idempotency key

The signup nonce is secret and becomes part of the short-lived onboarding credential. A calling Idempotency-Key is a separate identifier for one approved call. Never use the API key or onboarding token as a calling idempotency identifier.

Recovery and credits

The onboarding token expires in 30 minutes. SMS codes expire in 10 minutes, allow five incorrect attempts, and have a resend cooldown. Resume a pending signup with its original secret nonce and unchanged body, then request a new code if needed. Lost credentials, existing accounts, and missing password emails can recover through Cleo login and Forgot password. Knowing an existing email never issues its API key.

402 insufficient_credits means the included allowance and prepaid balance are exhausted. 402 insufficient_credits_for_call means some minutes remain but cannot cover the requested limit. Both include a dashboard action_url and retryable: false. No call starts or call credits are charged for the rejected request. Ask the user to log in and recharge; bots do not collect payment. Retry only after the user resolves the balance.

Instructions for bots

Send your assistant: “Muse, read cleopowered.com/llms.txt and follow the Cleo onboarding instructions.” The full agent recipe includes exact headers, recovery codes, call preparation and credit messages. Use the OpenAPI contract to configure your executor.

PreviousIntroduction

NextAPI overview