Developer Setup

Use the setup surface when you do not have a Flint API key yet.

The preferred setup flow is:

1. POST /v1/setup/start
2. POST /v1/setup/verify-email
3. GET /v1/setup/state
4. POST /v1/setup/advance as needed
5. POST /v1/setup/api-key
6. Switch to the normal /v1/... API with that API key

Methods

Preferred setup flow

Auth Model

Before you have an API key

• POST /v1/setup/start requires no auth
• POST /v1/setup/verify-email requires no auth, but it does require the emailed verification code and verification token

After verification

Use the returned token as:

Authorization: Bearer <developer_session_token>

You can also send:

X-Developer-Session-Token: <developer_session_token>

Authorization: Bearer ... is the recommended default.

Rate Limits

The setup surface has stricter anti-abuse rate limits than the normal /v1 resource API.

• POST /v1/setup/start is tightly limited
• POST /v1/setup/verify-email is tightly limited
• POST /v1/setup/api-key is also rate limited

GET /v1/setup/state and POST /v1/setup/advance still use setup auth, but they follow the normal authenticated route-class budgets after verification.

If you receive 429 rate_limit_error, back off and retry later.

For the current default limits across both setup and the broader public API, see Rate Limits.

Start Setup

Request Fields

Example

{
  "email": "owner@example.com",
  "first_name": "Jane",
  "last_name": "Doe"
}

{
  "data": {
    "verification_started": true,
    "verification_token": "devver_v1.c2FtcGxlLXZlcmlmaWNhdGlvbi10b2tlbg",
    "expires_at": "2026-03-18T20:00:00Z"
  },
  "request_id": "req_123"
}

Store verification_token temporarily. You send it back with the emailed verification code in the next step.

Verify Setup Email

Request Fields

Example

{
  "verification_token": "devver_v1.c2FtcGxlLXZlcmlmaWNhdGlvbi10b2tlbg",
  "verification_code": "482193"
}

{
  "data": {
    "developer_session_token": "devsess_v1.c2FtcGxlLWRldmVsb3Blci1zZXNzaW9uLXRva2Vu",
    "user": {
      "user_id": "usr_123",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "owner@example.com",
      "default_merchant_id": "mer_123",
      "status": "active",
      "created_at": "2026-03-18T19:45:00Z",
      "updated_at": "2026-03-18T19:45:00Z"
    },
    "merchant": {
      "merchant_id": "mer_123",
      "email": "owner@example.com",
      "status": "active",
      "onboarding_status": "not_started",
      "charges_enabled": false,
      "payouts_enabled": false,
      "details_submitted": false,
      "created_at": "2026-03-18T19:45:00Z",
      "updated_at": "2026-03-18T19:45:00Z"
    },
    "setup_state": "merchant_ready",
    "merchant_created": true,
    "default_sandbox_id": "test_01JQEXAMPLEDEFAULT12345678",
    "charges_enabled": false,
    "payouts_enabled": false,
    "details_submitted": false,
    "can_issue_api_key": true,
    "next_step": {
      "code": "check_onboarding_state",
      "owner": "agent",
      "surface": "api",
      "machine_completable": true,
      "submit_method": "GET",
      "submit_endpoint": "/v1/onboarding/state"
    }
  },
  "request_id": "req_123"
}

user.default_merchant_id is the setup default merchant selection for that developer identity.

Get Setup State

GET /v1/setup/state is the agent-friendly state machine surface. Instead of choosing between separate onboarding verbs, ask Flint what the next step is.

Key response fields:

• setup_state
• status
• next_step
• pending_steps
• profile
• provider
• provider_session
• requirements
• can_issue_api_key

Example:

{
  "data": {
    "merchant_id": "mer_123",
    "merchant_created": true,
    "email_verified": true,
    "default_sandbox_id": "test_01JQEXAMPLEDEFAULT12345678",
    "can_issue_api_key": true,
    "setup_state": "onboarding_available",
    "status": "needs_external_action",
    "next_step": {
      "code": "complete_verification_step",
      "owner": "human",
      "surface": "embedded",
      "machine_completable": false,
      "external_action": {
        "provider": "stripe",
        "kind": "embedded",
        "client_secret": "seti_123"
      }
    },
    "pending_steps": [],
    "profile": {
      "email": "owner@example.com"
    },
    "requirements": {
      "currently_due": [
        { "field": "external_account" }
      ]
    },
    "charges_enabled": false,
    "payouts_enabled": false,
    "details_submitted": false
  },
  "request_id": "req_123"
}

Top-level setup status values are:

• needs_input
• needs_external_action
• waiting_for_review
• ready_for_api_key
• complete

Advance Setup

POST /v1/setup/advance is the main mutating step. Send whatever you currently know and let Flint decide what should happen next.

Request Fields

Example

curl -X POST https://api.withflintpay.com/v1/setup/advance \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_DEVELOPER_SESSION_TOKEN" \
  -H "Idempotency-Key: setup-advance-001" \
  -d '{
    "profile": {
      "support_email": "help@example.com",
      "website_url": "https://example.com"
    },
    "country": "US",
    "artifacts": [
      {
        "provider": "stripe",
        "type": "account_token",
        "token": "tok_123"
      }
    ],
    "surface": "embedded"
  }'

If Flint still needs human completion, the response includes next_step.code = "complete_verification_step" and a provider_session.

Create Setup API Key

Create the first external API key for the current setup session.

Request Fields

Example response:

{
  "data": {
    "api_key_id": "key_123",
    "name": "First backend integration",
    "key_prefix": "flint_test_abcd1234",
    "key_type": "external",
    "status": "active",
    "secret_key": "flint_test_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  },
  "request_id": "req_123"
}

Store secret_key immediately. It is returned once.

After this step, stop treating the session as a setup workflow. New integrations should authenticate with the external API key, and future key management should happen through the normal /v1/api-keys resource API.

Next Steps

• API & Agent Onboarding
• Sandboxes API Reference
• API Keys
• OpenAPI
• Quickstart