Authentication

Every request to the Flint API goes to https://api.withflintpay.com and carries a secret API key. You send the key one of two ways, and the key itself decides everything else: whether the request runs in test or live mode, and for test mode, which sandbox it uses. Keys are secret and belong on your server only. This page covers how to send a key, how test and live keys differ, and what each authentication error means. If you just want to make your first call, start with Accept Your First Payment.

Making an Authenticated Request#

Put your key in the Authorization header as a bearer token. This call reads your account's card-payments capability and confirms the key works:

curl "https://api.withflintpay.com/v1/capabilities?capability=accept_card_payments" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    { "capability": "accept_card_payments", "status": "ready" }
  ],
  "request_id": "0b8f2b26-9c1e-4f6a-8d35-7e4a2c9b1d60",
  "meta": { "api_version": "2026-02-01" }
}

A successful response wraps the result under data, alongside a request_id and a meta object. List endpoints add a next_page_token for pagination. Every response, success or failure, also returns an x-request-id header carrying the same request id. If the call fails, the body is the error envelope instead.

The Two Header Schemes#

Flint accepts the key two ways. Use whichever fits your client; do not send both.

Authorization: Bearer YOUR_API_KEY

X-API-Key: YOUR_API_KEY

Flint does not accept HTTP Basic auth or a key passed as a query parameter. The key must travel in one of the two headers above.

Test and Live Keys#

A key's prefix decides its mode. Flint reads the prefix on every request; you never pass a mode flag.

For test cards, sandbox isolation, and resetting test data, see Sandboxes & Test Mode.

Where Keys Come From#

Every path below gives you a working key:

• The dashboard, at app.withflintpay.com/developers/api-keys. The fastest path, and test keys come sandbox-bound automatically.
• The API setup flow, to provision a merchant and mint the first key entirely over the API. See API & Agent Onboarding.
• A sandbox's test-key endpoint, POST /v1/developer/sandboxes/{sandbox_id}/test-key. See Sandboxes & Test Mode.
• The /v1/api-keys endpoints, covered in Managing Keys Over the API below.

The full secret key is shown only once, in the response that creates it. Capture it then; Flint never returns it again.

What a Key Looks Like#

A key has two identifiers, and telling them apart avoids most key-handling confusion. The key_-prefixed api_key_id names the key record and is safe to log and store; the flint_..._<random> string is the secret you actually send.

The rest of the key object is descriptive metadata:

Scopes and Permissions#

Each key carries a set of scopes such as commerce.orders.read, payments.payment_intents.write, or webhooks.webhooks.write. A request to an endpoint the key is not scoped for is rejected with 403, not 401.

When a key lacks the required scope, the response names it:

{
  "error": {
    "type": "authorization_error",
    "code": "INSUFFICIENT_SCOPE",
    "message": "The API key does not have the required scope: commerce.orders.write.",
    "request_id": "4a1f0c9e-2b7d-4f60-8c25-9e0b3d6f2a81"
  }
}

Unlike a 401, a scope 403 carries no WWW-Authenticate header. The missing scope is in the message, so you know exactly what to grant.

Managing Keys Over the API#

Alongside the dashboard, you can manage keys entirely over the API:

Listing your keys is a plain read:

curl "https://api.withflintpay.com/v1/api-keys?page_size=2" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "api_key_id": "key_01KWJ93G11C7MF8REX91MDS0CD",
      "name": "Production server",
      "key_prefix": "flint_live_1a2b3c4d",
      "sandbox_id": null,
      "scopes": ["commerce.orders.write", "payments.payment_intents.write"],
      "key_type": "external",
      "status": "active",
      "last_used_at": "2026-07-02T18:04:11Z",
      "created_at": "2026-06-01T09:12:00Z"
    }
  ],
  "next_page_token": "eyJjIjoia2V5XzAxS1cifQ",
  "request_id": "1b9d7c2a-4e8f-4a31-b7f0-5c9a2e8d4b36"
}

Creating a key returns the secret_key once. Two rules apply to the request:

• A test (sandbox-bound) caller must pass a sandbox_id; the new key is bound to that sandbox. A live caller must not pass one.
• You can only grant scopes the calling key already holds, so a key cannot escalate its own permissions.

curl -X POST https://api.withflintpay.com/v1/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer flint_test_YOUR_KEY" \
  -d '{
    "name": "CI runner",
    "scopes": ["commerce.orders.read"],
    "sandbox_id": "test_01KNB061AGD0CYYF16M5QAQE3N"
  }'

{
  "data": {
    "api_key_id": "key_01KWK4Q8Z1MB7F0T2S9R3V6HAX",
    "name": "CI runner",
    "key_prefix": "flint_test_9f8e7d6c",
    "secret_key": "flint_test_9f8e7d6c...",
    "sandbox_id": "test_01KNB061AGD0CYYF16M5QAQE3N",
    "scopes": ["commerce.orders.read"],
    "key_type": "external",
    "status": "active"
  }
}

There is no rotate endpoint. To rotate a key, create a new one and revoke the old:

Authentication and Authorization Errors#

Authentication failures return 401 with type: authentication_error and a WWW-Authenticate: Bearer realm="Flint API" header. Authorization failures (a valid key that lacks permission) return 403 with type: authorization_error and no WWW-Authenticate header. Every error uses the same envelope:

{
  "error": {
    "type": "authentication_error",
    "code": "API_KEY_NOT_FOUND",
    "message": "No API key matches the provided credential.",
    "request_id": "6f2c9a71-b0d3-4e58-9c16-7a4e0b2d8f53"
  }
}

SANDBOX_SELECTION_REQUIRED is the most common first-run failure, and it carries a remediation block telling you exactly what to do:

{
  "error": {
    "type": "authentication_error",
    "code": "SANDBOX_SELECTION_REQUIRED",
    "message": "Test mode API keys must be sandbox-bound before they can authenticate public API requests.",
    "remediation": {
      "retryable": false,
      "next_actions": [
        {
          "action_type": "issue_developer_sandbox_test_key",
          "reason_code": "SANDBOX_BOUND_TEST_KEY_REQUIRED",
          "reason_message": "Create or use a sandbox-bound test key for the sandbox this request should target.",
          "required_fields": ["sandbox_id"]
        }
      ]
    }
  }
}

Keep Your Keys Safe#

• Load keys from environment variables or a secrets manager, not from code.
• If a key leaks, revoke it immediately (via the API or the dashboard) and roll out a replacement.
• Grant each key the fewest scopes it needs, so a leak is contained.

For rotation policy, secret hygiene, and incident response in depth, see Key Security.

Next Steps#

• Sandboxes & Test Mode: how test keys bind to sandboxes and how to reset test data.
• Accept Your First Payment: make a real call now that your key works.
• API key scope catalog: every scope and what it grants.
• Error Handling: the full error envelope and retry strategy beyond auth.
• Going Live: swap your test key for a live key when you ship.
• Key Security: rotation, secret hygiene, and incident response.