Agent quick start

An AI agent should never ask its human to paste a key into a chat. It opens an onboarding session instead. The human approves it in the CreatoRain app, and the agent collects the key once. The flow follows the OAuth device grant (RFC 8628).

1. Open a session (no key)

curl -X POST "$CREATORAIN_API/onboarding_sessions" \
  -H "Content-Type: application/json" \
  -d '{"client_name":"My agent","requested_scopes":["read","locations:write"],"requested_livemode":false}'

The 201 answer carries:

user_code: eight letters, such as BCDF-GHJK. Show it to your human.
url: the app page where your human types the code.
session_secret (crp_obs_...): shown once. It is the only way to poll. Store it like a key.
interval: seconds between polls.
expires_at: 15 minutes after creation.

The scopes and mode you ask for are a request only. The human decides.

2. Show your human the code and the link

Say what you need and why. The workspace owner signs in, enters the code and approves. They pick the mode and the scopes.

3. Poll

curl "$CREATORAIN_API/onboarding_sessions/obs_..." \
  -H "Authorization: Bearer $SESSION_SECRET"

Poll every interval seconds. Sooner is 429 slow_down. The interval then grows by 5 seconds, up to 60, and Retry-After carries it.
status is pending, approved, denied or expired.
The first poll after approval carries key.secret. No later poll does: key_delivered turns true.
Lost the key? next_action is create_new_session. Open a new session.
blockers say why an approval cannot make a key yet. For example live_key_requires_top_up, key_limit_reached or owner_changed.

A wrong secret and an unknown id both answer 404. Failures count toward the address block, like bad keys.

Limits

5 sessions an hour per address, plus a global per-minute ceiling. Over it: 429 rate_limited with Retry-After.

Use the key as in the Quick start. Read llms.txt for the agent instructions.