# 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). **Not live yet:** The session calls are built. The approval page in the app (`/settings/api/connect`) is not live yet, and the API is not open on production. ## 1\. Open a session (no key) ```sh 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 ```sh 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`. ## Next Use the key as in the [Quick start](/get-started/quick-start/). Read [llms.txt](/llms.txt) for the agent instructions.