Skip to main content

​
Authentication

The Flowlix API uses Bearer token authentication. Every API request must include your secret API key in the Authorization header.

​
Making authenticated requests

Include your API key in the Authorization header using the Bearer scheme: 
curl https://api.flowlix.dev/v1/payments \
  -H "Authorization: Bearer fl_test_sk_abc123def456"

​
API key types

Flowlix provides two types of secret keys:
Key prefixEnvironmentPurpose
fl_test_sk_Test mode (sandbox)Development and testing. No real charges are made.
fl_live_sk_Live modeProduction. Real money is moved.
Both key types work identically with the API. The only differences are:
  • Test keys never create real charges or contact production payment networks.
  • Live keys process real payments against real cards.
  • Payments created with a test key have "livemode": false in the response.
  • Payments created with a live key have "livemode": true.
The mode of a payment is ultimately determined by the merchant record on file for that key, but in normal operation the key prefix and the merchant mode always agree.

​
Finding your keys

  1. Sign up at portal.flowlix.dev using Google or email.
  2. Enter your company name to create your merchant account.
  3. Go to Settings → API Keys in your Dashboard.
  4. Your sandbox keys (fl_test_sk_*) are available immediately.
  5. Live keys (fl_live_sk_*) are activated after KYB verification.
Your secret API key grants full access to your Flowlix account. Never share it publicly, commit it to version control, or include it in client-side code.

​
Key security best practices

  • Store keys in environment variables — never hardcode them in source files.
  • Use test keys in development — switch to live keys only in production deployments.
  • Rotate keys periodically — you can generate new keys in the Dashboard.
  • Restrict key permissions — use the Dashboard to limit what each key can do (coming soon).

​
Authentication errors

If the API key is missing, malformed, or revoked, the API returns a 401 Unauthorized response: 
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key provided.",
    "param": null,
    "decline_code": null,
    "doc_url": "https://docs.flowlix.dev/api-reference/authentication",
    "request_id": "req_abc123def456"
  }
}
The message field is one of the following, depending on what went wrong:
MessageCause
Missing or malformed Authorization header.Header missing entirely or not using the Bearer scheme.
Invalid API key format.The key does not start with fl_test_sk_ or fl_live_sk_.
Invalid API key provided.The key is well-formed but is unknown to Flowlix, has been revoked, or the merchant validation backend was temporarily unreachable.
If the key is well-formed and active but the merchant does not have permission for the requested operation, you receive 403 Forbidden with type: authentication_error and code: not_permitted instead.

​
Custom headers

In addition to Authorization, the API uses these headers:
HeaderDirectionDescription
Idempotency-KeyRequestEnsure write requests are processed exactly once. See Idempotency.
Flowlix-Request-IdResponseA unique correlation ID set by Flowlix on every response. Quote this value when contacting support.