# Open an onboarding session (no key) **Not live yet:** the v1 API and its hosts are not open. See [Sandbox](/get-started/sandbox/). POST /onboarding\_sessions Select code sampleFetchcURL ```js const url = 'https://api.creatorain.com/v1/onboarding_sessions'; const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"client_name":"example","requested_scopes":["read"],"requested_livemode":true}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url https://api.creatorain.com/v1/onboarding_sessions \ --header 'Content-Type: application/json' \ --data '{ "client_name": "example", "requested_scopes": [ "read" ], "requested_livemode": true }' ``` - Live (crp\_live\_ keys) - Sandbox (crp\_test\_ keys) No API key: this is how an agent without one starts. Show the human `user_code` and `url`. `session_secret` is returned ONCE and is the only way to poll; store it like a key. The requested scopes and mode are a request only: the approving human decides. 5 sessions an hour per address, and a global per-minute ceiling, then `429 rate_limited` with `Retry-After`. ## Request Body Media typeapplication/json object **client\_name** Shown to the human as an unverified name. string nullable <= 100 characters **requested\_scopes** Array nullable Allowed values: read samples:read locations:write balance:write creators:read webhooks:write **requested\_livemode** boolean nullable ## Responses ### 201 The session. Poll it every `interval` seconds until it is approved, denied or expired. Media typeapplication/json object **id** required string **object** required string Allowed values: onboarding\_session **status** required string Allowed values: pending **url** required string format: uri **user\_code** required Eight letters; the human types it in the app. string **session\_secret** required Shown once. The only way to poll this session. string **expires\_at** required 15 minutes after creation. string format: date-time **interval** required Seconds between polls. integer #### Example ```json { "id": "obs_3f2a9c1e5b7d4a6f8e0c2b4d6f8a0c2e", "object": "onboarding_session", "status": "pending", "url": "https://app.creatorain.com/settings/api/connect?code=BCDF-GHJK", "user_code": "BCDF-GHJK", "session_secret": "crp_obs_...", "interval": 5 } ``` #### Headers **Request-Id** string format: uuid This request’s id. Equal to error.request\_id; quote it to support. **Cache-Control** string Allowed values: no-store No-store. The answer may carry a secret. ### 400 Parameter\_invalid (with `field`) or invalid\_json. Media typeapplication/json object **error** required object **type** required string Allowed values: invalid\_request\_error authentication\_error permission\_error idempotency\_error rate\_limit\_error api\_error **code** required string Allowed values: parameter\_invalid invalid\_json idempotency\_key\_invalid idempotency\_key\_required customization\_not\_supported videos\_per\_month\_out\_of\_range batch\_invalid terms\_not\_accepted invalid\_key test\_key\_on\_live live\_key\_on\_sandbox insufficient\_balance scope\_missing forbidden\_ip forbidden live\_key\_requires\_top\_up limit\_raise\_requires\_dashboard not\_found idempotency\_conflict idempotency\_in\_progress conflict location\_already\_in\_network external\_id\_conflict dispute\_open request\_too\_large address\_not\_verified not\_food\_business metro\_not\_served package\_not\_available account\_location\_limit commit\_limit\_exceeded top\_up\_exceeds\_feasible no\_saved\_card rate\_limited quota\_exceeded slow\_down internal\_error service\_unavailable **message** required string **field** The request field at fault string **doc\_url** required string format: uri **request\_id** required string format: uuid **items** Batch\_invalid only. Every refused location, by its index in the request. Array