Key Security

A Flint integration holds two kinds of long-lived secrets: API keys (flint_test_... and flint_live_...) and webhook signing secrets (whsec_...). Either one, exposed, hands a stranger a piece of your payments stack. This guide is the operating manual for those secrets: where they belong, how to cap the damage a leak can do before it happens, and the exact playbook for the day one gets out. For how authentication itself works (headers, test vs live keys, error codes), see Authentication.

Every Flint Key Is a Secret Key#

Some payment APIs split credentials into a publishable half for the browser and a secret half for the server. Flint does not. There is no publishable key: every flint_ key is the secret half, authenticates as your merchant, and exercises every scope it holds. A flint_live_ key does all of that with real money.

The natural objection is "but my checkout runs in the browser". Buyer-facing surfaces never need your key. Hosted and embedded checkout authenticate the buyer with a short-lived session credential that your server mints, scoped to that one checkout and useless after it completes. Your key stays behind your API; the buyer's browser only ever holds the session credential. See Checkout Sessions and Embedded Payments for how those flows keep the key server-side.

Just as important is knowing which values are not secret. Every Flint credential splits into a safe identifier and secret material:

Flint stores only an irreversible hash of each key, which is why the full secret_key appears exactly once, in the response that creates it. That is a feature, not a limitation: nothing that reads Flint's records can recover your key, and neither can Flint support. If you lose a key, you do not recover it; you rotate it.

Keep Secrets Out of Code and Source Control#

Code gets copied, forked, reviewed, pasted into tickets, and fed to tools. Configuration does not have to be. Load keys from the environment or a secrets manager (AWS Secrets Manager, Vault, Doppler, your platform's equivalent), and keep the values out of the repository entirely:

# .env (never committed)
FLINT_API_KEY=flint_live_...
FLINT_WEBHOOK_SECRET=whsec_...

# .gitignore
.env
.env.*

In CI, use the provider's secret store rather than checked-in config, and make sure the values are masked in job logs. A key that prints in a public build log is just as leaked as one in a commit.

Add secret scanning to CI and pre-commit hooks. Flint credentials are built to be scanned for: every key starts with flint_test_ or flint_live_, and every webhook secret with whsec_, so a scanner rule is a simple prefix match. Catching a key in review costs a minute; catching it in production costs the rest of this guide.

Scope Keys to the Job#

A key's scopes are its blast radius. The habit that contains a leak before it happens is one key per workload, named after where it runs, holding only the scopes that job needs:

• One key per service or integration. "Storefront backend", "Reporting worker", "CI runner". When one leaks you revoke it without touching the others, and each key's last_used_at tells a clean story about a single workload.
• Fewest scopes that do the job. A .write scope also satisfies the matching .read, so granting commerce.orders.write covers both; you never need to grant the pair.
• Keys cannot escalate. Creating or updating a key over the API can only grant scopes the calling key itself holds. A leaked read-only key cannot mint itself a broader one.

A reporting service that only reads orders and payments needs exactly that and nothing more:

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

If this key leaks, the attacker can read order and payment data, which is bad. They cannot create refunds, touch payouts, or issue new keys, which is much worse. Least privilege does not prevent the incident; it caps its cost.

Expire Keys That Should Not Live Forever#

Some keys have a natural end date: a contractor's engagement, a one-off migration script, a load test, a demo. Set expires_at when you create the key and it shuts itself off on schedule, whether or not anyone remembers it exists:

curl -X POST https://api.withflintpay.com/v1/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer flint_test_YOUR_KEY" \
  -d '{
    "name": "Catalog migration (temporary)",
    "scopes": ["commerce.products.write"],
    "sandbox_id": "test_01KNB061AGD0CYYF16M5QAQE3N",
    "expires_at": "2026-08-01T00:00:00Z"
  }'

• expires_at is an RFC 3339 timestamp and must be in the future. Omit it and the key never expires.
• PATCH /v1/api-keys/{api_key_id} can set or move the date on an existing key, or clear it with "expires_at": null, so you can extend access without minting a new key.
• Once the moment passes, the key fails closed: every request returns 401 API_KEY_EXPIRED. Issue a new key if the work genuinely is not done.

An expiring key is the cheapest security control Flint offers: nothing to remember, nothing to clean up, and the failure mode is a loud 401 instead of a forgotten credential with production access.

Rotate Keys Without Downtime#

Rotation puts an upper bound on how long a stolen-but-undetected key stays useful. There is deliberately no rotate endpoint for API keys; rotation is create, deploy, revoke, and because old and new keys both authenticate during the overlap, traffic never drops:

Rotate on events, not just on a calendar: whenever someone with access to production secrets leaves, and after any security incident at a vendor that held the key (your CI provider, log aggregator, or host). A fixed cadence on top of that, quarterly is common, keeps the muscle exercised so rotation day is routine instead of an emergency drill.

last_used_at also makes a periodic key audit cheap. List your keys and read the timestamps:

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

{
  "data": [
    {
      "api_key_id": "key_01KWJ93G11C7MF8REX91MDS0CD",
      "name": "Storefront backend",
      "key_prefix": "flint_test_1a2b3c4d",
      "scopes": ["commerce.orders.write", "payments.payment_intents.write"],
      "status": "active",
      "last_used_at": "2026-07-03T09:14:07Z",
      "created_at": "2026-04-18T12:00:00Z"
    },
    {
      "api_key_id": "key_01KWK4Q8Z1MB7F0T2S9R3V6HAX",
      "name": "Load test (March)",
      "key_prefix": "flint_test_9f8e7d6c",
      "scopes": ["commerce.orders.write"],
      "status": "active",
      "last_used_at": "2026-03-30T16:41:22Z",
      "created_at": "2026-03-12T08:30:00Z"
    }
  ],
  "request_id": "2f8c1d9a-4b7e-4c53-8d30-a9f2c5e7b481"
}

The second key tells its own story: created for a March load test, unused since. A key nobody uses is pure liability, so revoke it:

curl -X POST https://api.withflintpay.com/v1/api-keys/key_01KWK4Q8Z1MB7F0T2S9R3V6HAX/revoke \
  -H "Authorization: Bearer flint_test_YOUR_KEY"

Webhook Signing Secrets#

Webhook signing secrets deserve the same handling as keys, because a leaked whsec_ enables a quieter attack: it does not let anyone call your API, but it lets them forge events to your webhook handler. A convincing fake order.payment_succeeded aimed at a fulfillment handler ships product that was never paid for. Store whsec_ values exactly like keys, and rotate them with the same urgency.

Each webhook endpoint has its own secret, per endpoint and per mode, returned once when the endpoint is created. Two things work differently from API keys:

And secrets are mode-specific: sandbox endpoints get sandbox secrets, live endpoints get live secrets. Carrying a sandbox whsec_ into production config is the classic go-live webhook failure; every live event fails verification until you swap in the live endpoint's secret. Signature verification itself, raw-body handling, and the rotation overlap in practice are covered in Webhooks.

If a Key Leaks#

A key committed to a repo, pasted into a ticket or chat, printed in a build log, or one you simply cannot account for: run this playbook. Speed beats certainty. Your integration erroring for a few minutes is recoverable; an attacker holding a live key is not. If you are unsure whether a key actually leaked, revoke it anyway and let the playbook answer the question.

curl -X POST https://api.withflintpay.com/v1/api-keys/key_01KWJ93G11C7MF8REX91MDS0CD/revoke \
  -H "Authorization: Bearer flint_live_YOUR_KEY"

Key Security Checklist#

• keys live in server-side env vars or a secrets manager, never in code, client bundles, or commits
• .env files are gitignored, and secret scanning watches for flint_test_, flint_live_, and whsec_ prefixes
• CI uses the provider's secret store and masks secrets in job logs
• one key per service, named for where it runs, holding only the scopes that job needs
• temporary access gets expires_at, not a calendar reminder
• rotation has an owner and a cadence, and also runs on offboarding and vendor incidents
• keys with a stale last_used_at get revoked, not kept just in case
• whsec_ secrets are handled like keys and rotated with the same urgency
• everyone on call knows the revoke path before they need it

Next Steps#

• Authentication: how keys authenticate, test vs live modes, and every auth error code.
• API key scope catalog: every scope and what it grants.
• Webhooks: signature verification and secret rotation in practice.
• Going Live: the credential swap from sandbox to production.
• Sandboxes & Test Mode: why test keys are sandbox-bound and how to reset test data.
• Rate Limits: the per-key and per-merchant budgets that govern every key.