Developer setup
Use the onboarding surface when you do not have a Flint API key yet.
Most developers should not start here. If you can use the dashboard, create a test API key there and go to Accept your first payment.
The flow is a state machine under /v1/onboarding/...:
POST /v1/onboarding/startPOST /v1/onboarding/verify-emailGET /v1/onboarding/statePOST /v1/onboarding/advanceas neededPOST /v1/merchant-account-sessionswhennext_step.launchrequires a browser- Poll onboarding state after the browser closes
POST /v1/onboarding/api-key- Switch to the normal
/v1/...API with that API key
This flow keeps merchant provisioning and first-key issuance in your integration. Account verification may still pause for a human to complete a browser step described by next_step.launch. Mint the browser action separately with POST /v1/merchant-account-sessions; browser exit is not completion.
For full request and response shapes, see the Onboarding API reference. For a step-by-step walkthrough, see API & agent onboarding.
How it works#
POST /v1/onboarding/start requires no auth. It emails a verification code and returns a temporary verification_token.
POST /v1/onboarding/verify-email exchanges the emailed code plus verification_token for an onboarding_session_token, provisioning the Flint user, merchant, and a default private sandbox if needed.
From there, read GET /v1/onboarding/state and follow next_step through POST /v1/onboarding/advance calls until status is ready_for_api_key, then create the first external key with POST /v1/onboarding/api-key. The response includes the one-time data.secret_key.
Verification is email-gated. Agents need either a human-in-the-loop or mailbox access to read the emailed code. verification_token currently expires after 15 minutes, and onboarding_session_token is minted for 24 hours.
Auth model#
onboarding_session_token is a short-lived onboarding token. It works on /v1/onboarding/... routes and does not authenticate normal resource requests like /v1/orders. Send it as:
Authorization: Bearer <onboarding_session_token>
You can also send:
X-Onboarding-Session-Token: <onboarding_session_token>
Authorization: Bearer ... is the recommended default.
After the first key exists, GET /v1/onboarding/state and POST /v1/onboarding/advance also accept a normal external API key for later compliance remediation.
Sandbox-management routes under /v1/developer/sandboxes/... accept the same onboarding_session_token during setup or a normal external API key afterward. See Sandboxes.
Rate limits#
The onboarding surface has stricter anti-abuse rate limits than the normal /v1 resource API. POST /v1/onboarding/start, POST /v1/onboarding/verify-email, and POST /v1/onboarding/api-key are tightly limited per IP. If you receive 429 rate_limit_error, back off and retry later. See Rate limits.