Authentication and keys

Sending your key

Every API endpoint except the keyless discovery endpoints takes your key in one of two headers:

curl https://api.framequery.com/v1/api/jobs \
  -H "Authorization: Bearer $FRAMEQUERY_API_KEY"

# Same key, alternative header
curl https://api.framequery.com/v1/api/jobs \
  -H "X-API-Key: $FRAMEQUERY_API_KEY"

A missing, invalid, revoked or expired key returns 401 with code UNAUTHORIZED. The SDKs read the key from the FRAMEQUERY_API_KEY environment variable when you do not pass one.

These endpoints need no key at all, so you can explore prices and formats before you sign up: GET /openapi.json, GET /pricing, GET /pricing/estimate and GET /formats.

Getting a key

Keys are Polar license keys. Polar is our billing provider, and it issues a key with the prefix fq_live_ when you buy API credits:

1. During the public beta, request access by email; we switch accounts on one by one. Once yours is on, sign in and open the API keys page.
2. Buy a credit pack ($10, $50 or $100). Checkout runs on Polar.
3. Open the Polar customer portal with the Open Polar portal button on the API keys page to see the full key. The API keys page itself lists your keys with the secret masked.

There is no API endpoint that creates keys, and no way to create one with another key. Keys carry no scopes during the beta: every valid key has full access to its account's jobs, results and balance, and all keys of an account share its rate limits and credits.

Verify a key and see your balance in one call:

curl https://api.framequery.com/v1/api/quota \
  -H "Authorization: Bearer $FRAMEQUERY_API_KEY"

Keep keys server-side

A key can spend your credits, so treat it like a password:

• Call the API from your backend, a job runner or a script. Never put a key in browser JavaScript, a mobile app or a public repository.
• Read it from an environment variable or a secrets manager, not from source code.
• The TypeScript SDK refuses to construct a client with a key inside a browser unless you pass dangerouslyAllowBrowser: true. Do not.

Rotating a key

Rotate a key whenever it may have leaked, and on a regular schedule:

1. On the API keys page, click Rotate next to the key.
2. The new key is shown once. Copy it into your secret store straight away.
3. The old key stops working. Requests that still use it start returning 401 UNAUTHORIZED, everywhere within about a minute (validated keys are cached for up to 60 seconds).

Because rotation is immediate, deploy the new key first if you can: rotate, update your secret store, redeploy, and expect a brief window of 401s from anything still holding the old key.

Dashboard-only endpoints

Key and webhook-secret management is done from the FrameQuery dashboard and is authenticated with your signed-in session, not with an API key. These endpoints appear in the OpenAPI document under the Keys and Webhooks tags for completeness; an fq_live_ key cannot call them.

Failure modes