API Keys
API keys authenticate your requests to Flint Pay. Each key has scoped permissions controlling which APIs it can access. Keys use the key_ ID prefix.
If you do not have your first API key yet, start with the Developer Setup surface or the API & Agent Onboarding guide.
If you need isolated test environments, use Sandboxes to create or reset sandboxes and issue sandbox-bound test keys.
If you are sizing workers or retry loops, see Rate Limits for the current default limits and 429 handling guidance.
Methods#
Manage keys over the API with the /v1/api-keys endpoints: list (GET /v1/api-keys), create (POST /v1/api-keys), retrieve (GET /v1/api-keys/{api_key_id}), update (PATCH /v1/api-keys/{api_key_id}), and revoke (POST /v1/api-keys/{api_key_id}/revoke). Creating a key returns its secret_key once. See the Authentication guide for request rules and examples.
To create your very first key, before you have one to authenticate with, use one of these flows instead:
- Create your first key during Developer Setup.
- Issue sandbox-bound test keys from Sandboxes after setup.
- Create and manage keys in the Flint dashboard.
secret_key values are only shown once at creation time. Store them securely. Flint cannot return the same secret again later.
Key Format#
Test keys start with flint_test_, live keys with flint_live_. Use test keys for sandbox and other test-mode environments. Live keys should only be used for production traffic.
When you create a key with sandbox_id, Flint binds that test key to a specific sandbox. Requests made with that key execute inside that sandbox automatically; you do not send a separate sandbox selector on each request.
Sandbox-bound keys are only valid for active test sandboxes owned by the authenticated merchant.
Key Statuses#
| Status | Description |
|---|---|
active | Key is valid and can authenticate requests |
revoked | Key has been permanently revoked and cannot be used |
Available Scopes#
Each scope grants access to specific API operations. Use the narrowest set of scopes your integration requires. The table is generated from the same catalog used by API-key validation and the dashboard pickers.
Credentials and API keys
| Scope | Permission | Key modes | Partner installs |
|---|---|---|---|
accounts.api_keys.read | Read api keys | live, test | Not allowed |
accounts.api_keys.write | Write api keys | live, test | Not allowed |
Developer tools
| Scope | Permission | Key modes | Partner installs |
|---|---|---|---|
developer.partner_apps.read | Read partner apps | live | Not allowed |
developer.partner_apps.write | Write partner apps | live | Not allowed |
developer.sandboxes.read | Read sandboxes | live | Not allowed |
developer.sandboxes.write | Write sandboxes | live | Not allowed |
Merchant account
| Scope | Permission | Key modes | Partner installs |
|---|---|---|---|
merchants.profile.read | Read merchant profile | live, test | Allowed |
merchants.profile.write | Write merchant profile | live, test | Not allowed |
merchants.onboarding.read | Read onboarding | live, test | Not allowed |
merchants.account_sessions.write | Write merchant account sessions | live, test | Not allowed |
merchants.onboarding.write | Write onboarding | live, test | Not allowed |
merchants.locations.read | Read locations | live, test | Allowed |
merchants.locations.write | Write locations | live, test | Allowed |
merchant_billing.read | Read merchant billing | live, test | Not allowed |
Developer and account
| Scope | Permission | Key modes | Partner installs |
|---|---|---|---|
accounts.organizations.read | Read organizations | live, test | Not allowed |
accounts.organizations.write | Write organizations | live, test | Not allowed |
settings.read | Read settings | live, test | Not allowed |
settings.write | Write settings | live, test | Not allowed |
accounts.devices.read | Read devices | live, test | Not allowed |
accounts.devices.write | Write devices | live, test | Not allowed |
analytics.read | Read analytics | live, test | Allowed |
webhooks.read | Read webhooks | live, test | Allowed |
webhooks.write | Write webhooks | live, test | Allowed |
developer.request_logs.self.read | Read own request logs | live, test | Not allowed |
developer.request_logs.self.detail.read | Read own request log details | live, test | Not allowed |
developer.resource_timelines.read | Read resource timelines | live, test | Not allowed |
Customers
| Scope | Permission | Key modes | Partner installs |
|---|---|---|---|
customers.read | Read customers | live, test | Allowed |
customers.write | Write customers | live, test | Allowed |
customers.sessions.write | Write customer sessions | live, test | Not allowed |
Commerce
| Scope | Permission | Key modes | Partner installs |
|---|---|---|---|
commerce.coupons.read | Read coupons | live, test | Allowed |
commerce.coupons.write | Write coupons | live, test | Allowed |
commerce.products.read | Read products | live, test | Allowed |
commerce.products.write | Write products | live, test | Allowed |
commerce.orders.read | Read orders | live, test | Allowed |
commerce.orders.write | Write orders | live, test | Allowed |
commerce.refunds.read | Read refunds | live, test | Allowed |
commerce.refunds.write | Write refunds | live, test | Allowed |
commerce.subscription_plans.read | Read subscription plans | live, test | Allowed |
commerce.subscription_plans.write | Write subscription plans | live, test | Allowed |
commerce.subscriptions.read | Read subscriptions | live, test | Allowed |
commerce.subscriptions.write | Write subscriptions | live, test | Allowed |
commerce.invoices.read | Read invoices | live, test | Allowed |
commerce.invoices.write | Write invoices | live, test | Allowed |
commerce.bundles.read | Read bundles | live, test | Allowed |
commerce.bundles.write | Write bundles | live, test | Allowed |
commerce.catalog.read | Read catalog | live, test | Allowed |
commerce.catalog.write | Write catalog | live, test | Allowed |
commerce.refunds.tax_overrides.write | Write refund tax overrides | live, test | Not allowed |
commerce.promotions.read | Read promotions | live, test | Allowed |
commerce.promotions.write | Write promotions | live, test | Allowed |
commerce.inventory.read | Read inventory | live, test | Allowed |
commerce.inventory.write | Write inventory | live, test | Allowed |
commerce.inventory_policies.write | Write inventory policies | live, test | Allowed |
commerce.inventory_locations.write | Write inventory location authority | live, test | Allowed |
commerce.inventory_reservations.write | Write inventory reservations | live, test | Allowed |
commerce.returns.read | Read returns | live, test | Allowed |
commerce.returns.write | Write returns | live, test | Allowed |
commerce.returns.decisions.write | Write return decisions | live, test | Allowed |
commerce.returns.operations.write | Write return operations | live, test | Allowed |
commerce.returns.resolutions.write | Write return resolutions | live, test | Allowed |
commerce.returns.process.write | Write composite return processing | live, test | Allowed |
commerce.return_policies.write | Write return policies | live, test | Allowed |
commerce.return_reasons.write | Write return reasons | live, test | Allowed |
commerce.delivery.read | Read delivery | live, test | Allowed |
commerce.delivery.write | Write delivery | live, test | Allowed |
Payments
| Scope | Permission | Key modes | Partner installs |
|---|---|---|---|
checkouts.checkout_sessions.read | Read checkout sessions | live, test | Allowed |
checkouts.checkout_sessions.write | Write checkout sessions | live, test | Allowed |
payments.payment_intents.read | Read payment intents | live, test | Allowed |
payments.payment_intents.write | Write payment intents | live, test | Allowed |
payments.payment_methods.read | Read payment methods | live, test | Allowed |
payments.payment_methods.write | Write payment methods | live, test | Allowed |
checkouts.payment_links.read | Read payment links | live, test | Allowed |
checkouts.payment_links.write | Write payment links | live, test | Allowed |
payments.disputes.read | Read disputes | live, test | Not allowed |
capabilities.read | Read capabilities | live, test | Not allowed |
payments.payment_options.read | Read payment options | live, test | Allowed |
payments.payment_method_domains.read | Read payment method domains | live, test | Not allowed |
payments.payment_method_domains.write | Write payment method domains | live, test | Not allowed |
Risk
| Scope | Permission | Key modes | Partner installs |
|---|---|---|---|
risk.read | Read risk data | live, test | Allowed |
risk.reviews.write | Write risk reviews | live, test | Allowed |
risk.controls.write | Write risk controls | live, test | Allowed |
Money movement
| Scope | Permission | Key modes | Partner installs |
|---|---|---|---|
money_movement.balances.read | Read balances | live, test | Not allowed |
money_movement.balance_transactions.read | Read balance transactions | live, test | Not allowed |
money_movement.payouts.read | Read payouts | live, test | Not allowed |
money_movement.payouts.write | Write payouts | live, test | Not allowed |
money_movement.payout_settings.read | Read payout settings | live, test | Not allowed |
money_movement.payout_settings.write | Write payout settings | live, test | Not allowed |
reports.read | Read reports | live, test | Allowed |
reports.write | Write reports | live, test | Allowed |
Scope evaluation#
A matching write scope satisfies its read scope. For example, commerce.orders.write satisfies a route requiring commerce.orders.read. A write scope does not satisfy reads for a sibling resource, and unqualified scopes do not imply qualified permissions such as commerce.refunds.tax_overrides.write.
all is reserved for trusted internal keys and cannot be granted to an external API key.
Payment scopes follow ownership, not resource type#
A payment intent that belongs to an order is authorized by the order's scopes, not by payments.payment_intents.write. The route you call decides the scope you need.
| Route | Required scope |
|---|---|
POST /v1/payment-intents (standalone) | payments.payment_intents.write |
PATCH, /confirm, /capture, /cancel under /v1/payment-intents/{id} | payments.payment_intents.write |
POST /v1/orders/{order_id}/payment-intents | commerce.orders.write |
POST /v1/orders/{order_id}/pay | commerce.orders.write |
POST /v1/orders/{order_id}/payment-intents/{id}/capture | commerce.orders.write |
POST /v1/orders/{order_id}/payment-intents/{id}/cancel | commerce.orders.write |
POST /v1/orders/{order_id}/payment-attempts/{id}/cancel | commerce.orders.write |
GET /v1/orders/{order_id}/payment-attempts and /{id} | commerce.orders.read |
GET /v1/payment-intents and /{id} | payments.payment_intents.read |
A key holding only payments.payment_intents.write receives INSUFFICIENT_SCOPE on every order-scoped payment route. The error's scope_requirement and missing_scopes fields name the exact missing authority.