Core concepts

Authentication and scopes

Every request carries an API key in the Authorization header. The key belongs to one organization, and its scopes decide what it can do.

API keys#

HTTP header

Authorization: ApiKey flx_live_<43 letters and digits>

An organization admin creates keys in the Flux app under Settings → Developers, names them and chooses their scopes. See Set up an integration.
Keys start with flx_live_ followed by 43 letters and digits. There are no test keys: use a staging organization for testing.
The full key is shown once. Flux stores only a hash, so a lost key can't be recovered. Create a new key and revoke the old one.
A revoked key stops working at once.
The scheme is ApiKey, not Bearer. Session tokens from the Flux web app aren't accepted on /api/v1.

curl "$FLUX_BASE_URL/api/v1/invoices" \
  -H "Authorization: ApiKey $FLUX_API_KEY"

const headers = { Authorization: `ApiKey ${process.env.FLUX_API_KEY}` };

headers = {"Authorization": f"ApiKey {os.environ['FLUX_API_KEY']}"}

$headers = ['Authorization: ApiKey ' . getenv('FLUX_API_KEY')];

http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("ApiKey", Environment.GetEnvironmentVariable("FLUX_API_KEY"));

req.Header.Set("Authorization", "ApiKey "+os.Getenv("FLUX_API_KEY"))

Scopes#

Each endpoint needs one scope, shown on its reference entry. A :write scope includes the matching :read scope.

Scope	Allows
`customers:read`	Read customers, their enrollments and statements.
`customers:write`	Create and update customers. Includes `customers:read`.
`invoices:read`	Read invoices and receipts, and create signed links.
`invoices:write`	Raise invoices. Includes `invoices:read`.
`payments:read`	Read payment attempts. Also adds `payments` to `GET /invoices/{id}`.
`payments:write`	Start a checkout. Includes `payments:read`.
`webhooks:manage`	Manage webhook endpoints and deliveries.

One key, one organization#

Everything a key reads or creates belongs to the key's organization. You never send an organization id.
Another organization's ids behave as if they don't exist: you get 404 not_found, not 403.
Customers and invoices created through the API are recorded as created by the admin who made the key, and go through the organization's normal workflow.

Handling keys#

Call the API from your server. Never put a key in browser or mobile app code: anyone could read it.
Keep keys in a secret manager or in environment variables injected at runtime. Keep them out of source control, URLs, logs, tickets and email.
Redact the Authorization header in your HTTP logs and monitoring.
Give each system its own key with only the scopes it needs. Each key also has its own rate limit.
To replace a key without downtime, see Rotate keys and secrets.

Authentication errors#

Don't retry these: fix the key or its scopes first.

401 Unauthorized: no key, an unknown key or a revoked key

{
  "code": "unauthorized",
  "message": "Send a valid API key as 'Authorization: ApiKey <key>'.",
  "details": null
}

403 Forbidden: the key lacks the scope

{
  "code": "insufficient_scope",
  "message": "This API key does not have the 'invoices:write' scope.",
  "details": {
    "required": "invoices:write"
  }
}