Using an API key

Every call to the public Face API needs an X-Api-Key header carrying the full key string. There are no other credential surfaces today.

The header

X-Api-Key: bfq_live_…

Send the full string the dashboard showed you at mint time. Don't truncate.

What the key controls

A valid key identifies the caller's account and the project the call belongs to. The project binding determines:

Which gallery identify and verify search.
Which budget the call draws from.
Which rate-limit bucket the call counts against.
Where the call shows up in Analytics and Money Audit.

In Isolated mode the gallery is scoped to that project only; in Shared mode all Shared projects in the same account share a gallery.

A canonical call

bash

curl -X POST https://api.biofrq.com/v1/face/execute \
  -H "X-Api-Key: bfq_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "biofrq.detect",
    "params": {
      "images": [
        { "kind": "image", "bytes": "<base64>", "contentType": "image/jpeg" }
      ]
    }
  }'

See Envelope for the full request shape that every action follows.

What the dashboard sees

Every billable call produces a RequestLog row pinned to your key. You can drill into it from the Money Audit tab — by key, by project, by action, by error code, by date range.

Auth failure modes

Code	When	What to do
`UNAUTHORIZED`	Header missing or string unknown	Verify you're sending the full key string, not a truncated copy.
`UNAUTHORIZED` (revoked)	Key was revoked in the dashboard	Mint a new one or rotate the existing one.
`UNAUTHORIZED` (expired)	Key past its `expiresAtUtc`	Mint a new one.
`FORBIDDEN`	Key valid but lacks permission for this action / project	Check the project binding; this is rare in v0.
`PAYMENT_REQUIRED`	Project budget exhausted	Allocate more from the wallet.
`RATE_LIMITED`	Project burst or sustained RPS exceeded	Back off with jitter; consider raising the limit in the dashboard.