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/onboarding/api-key- Switch to the normal
/v1/...API with that API key
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 currently 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.