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.
Accounts#
| Scope | Description |
|---|---|
accounts.api_keys.read | Read API key metadata where supported |
accounts.api_keys.write | Create, update, and revoke API keys, including sandbox-bound test keys |
accounts.devices.read | Read devices |
accounts.devices.write | Create, update, delete devices |
accounts.merchants.read | Read merchant details |
accounts.merchants.write | Update merchant profile |
Customers#
| Scope | Description |
|---|---|
customers.customers.read | Read customers |
customers.customers.write | Create, update customers |
Commerce#
| Scope | Description |
|---|---|
commerce.orders.read | Read orders |
commerce.orders.write | Create, update, close, and pay orders; mutate line items, discounts, requested tip, and tax |
commerce.products.read | Read products |
commerce.products.write | Create, update, delete products, variants, and bundles; replace categories; adjust variant inventory |
commerce.coupons.read | Read coupons |
commerce.coupons.write | Create, update, delete coupons; replace product restrictions |
commerce.refunds.read | Read refunds |
commerce.refunds.write | Create refunds |
commerce.invoices.read | Read invoices, invoice events, invoice delivery attempts, and invoice PDFs |
commerce.invoices.write | Create, update, send, void, remind, and collect invoices |
commerce.subscriptions.read | Read subscriptions |
commerce.subscriptions.write | Create, update, cancel, pause, resume subscriptions |
commerce.subscription_plans.read | Read subscription plans |
commerce.subscription_plans.write | Create, update, archive plans |
Payments#
| Scope | Description |
|---|---|
payments.payment_intents.read | Read payment intents |
payments.payment_intents.write | Create, update, confirm, capture, and cancel payment intents |
payments.payment_methods.read | Read payment methods |
payments.payment_methods.write | Save, remove, and set default payment methods |
Checkouts#
| Scope | Description |
|---|---|
checkouts.checkout_sessions.read | Read checkout sessions |
checkouts.checkout_sessions.write | Create, update, and close checkout sessions |
checkouts.payment_links.read | Read payment links |
checkouts.payment_links.write | Create, update, replace content, activate, and deactivate payment links |
Settings & Analytics#
| Scope | Description |
|---|---|
settings.settings.read | Read settings |
settings.settings.write | Update settings |
analytics.read | Read analytics data |
developer.logs.self.read | Read API request logs for the current API key only |
Webhooks#
| Scope | Description |
|---|---|
webhooks.webhooks.read | Read webhook endpoints and webhook delivery events |
webhooks.webhooks.write | Create, update, delete, and rotate webhook endpoints |
Defined But Not Currently Used By Public /v1 Routes#
These scopes exist in the shared scope enum and may appear in internal or future surfaces, but this public API does not currently expose /v1 routes that require them:
| Scope |
|---|
accounts.locations.read |
accounts.locations.write |
accounts.organizations.read |
accounts.organizations.write |
analytics.write |
Special Case#
all exists in the shared scope model, but external API keys cannot grant it.