Authentication

When to use this page

Use this page when wiring Quotaflow into an SDK, server, CI job, or agent runtime.

Bearer token

Quotaflow accepts a qf_... API key as a bearer token. The key authenticates the request. Every active key must be attached to an explicit organization, project, subscription, package, or contract billing profile. Removed balance-backed billing contexts are rejected.

Authorization: Bearer qf_your_key_here

Alternate headers

Some clients cannot set Authorization. Quotaflow also accepts:

x-api-key: qf_your_key_here

or:

x-goog-api-key: qf_your_key_here

AK/SK signed requests

Enterprise keys can also be issued as an Access Key / Secret Key pair. Use this mode when your security policy requires request signing or replay protection. Do not send a bearer API key on the same request.

Send these headers:

X-QF-Access-Key: qfak_your_access_key
X-QF-Timestamp: 1782969000
X-QF-Nonce: unique-nonce-per-request
X-QF-Content-SHA256: lowercase_sha256_hex_of_request_body
X-QF-Signature: lowercase_hmac_sha256_hex

The signature is HMAC-SHA256(secret_key, canonical_request), where canonical_request is:

METHOD
/path
raw_query_string
unix_timestamp_seconds
nonce
sha256_hex_body

Timestamps must be close to server time, and each nonce can only be used once during the replay window. The secret key is shown only when the credential is created; store it in a server-side secret manager.

Security rules

• Never commit API keys.
• Never place API keys in frontend JavaScript.
• Use different keys per customer, environment, or workload when you need separate permissions, audit trails, or revocation boundaries. Do not assume each key has a separate balance.
• Rotate a key immediately if it appears in logs, screenshots, crash reports, or support tickets.

Common authentication errors

{
  "error": "Missing API key",
  "message": "Please provide an API key in the x-api-key, x-goog-api-key, or Authorization header"
}

This means no key reached the API.

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error"
  }
}

This means the key is missing, disabled, expired, deleted, or from a different environment.