API Keys

API keys authenticate every request. Each key belongs to one organization and carries explicit scopes. Keys are created and revoked from the dashboard. They’re shown exactly once on creation, so copy them then.

Publishable and server keys

There are two kinds of key. Pick by where the code runs.

Kind	Scopes	Can call	Where it lives
Publishable	public	GET /faqs and GET /search, published content only	Browser code, mobile apps, anywhere
Server	read, write, admin	Every endpoint its scopes allow, including drafts and unpublished translations	Server environment variables only

A publishable key can’t read drafts, unpublished translations, product facts, key metadata or settings, and it can’t change anything. Every other endpoint answers 403 forbidden. It still counts toward your rate limit and monthly quota, so revoke and replace it if someone abuses it.

A read key is not safe in a browser: it reads draft questions and private product facts. Never put a server key in client code, a VITE_* or NEXT_PUBLIC_* variable, or a URL.

public can’t be combined with read, write or admin on one key. Create two keys instead. Existing read keys keep working on /faqs and /search.

List

curl https://api.thefaq.app/api/v1/acme/api-keys \
  -H "Authorization: Bearer $FAQAPP_API_KEY"

Response:

{
  "data": [
    {
      "id": "key_8X3F",
      "name": "production-web",
      "scopes": ["read", "write"],
      "lastUsedAt": "2026-05-20T09:14:08Z",
      "createdAt": "2026-04-12T10:00:00Z",
      "fingerprint": "a14b2c…"
    }
  ],
  "meta": { "pagination": { "page": 1, "limit": 20, "total": 1, "pages": 1 } }
}

The full key value is never returned by list. Only the SHA-256 fingerprint (first 6 chars) is shown for identification.

Required scope: read. A publishable key can’t list keys.

Create and revoke

Create and revoke keys in the dashboard under Settings, then API keys. A key with the admin scope can also call POST /api-keys and DELETE /api-keys/:id, or faq.apiKeys.create and faq.apiKeys.revoke in the SDK. The full key value appears once, in the create response.

When you create a key:

1. Pick a name (visible later on the list endpoint above)
2. Pick Publishable for browser code, or Server (read, write) for backends
3. Copy the key value immediately. It’s shown once.

When you revoke a key, every request using it starts returning 401 unauthorized instantly. There’s no grace period.

Rotation pattern

1. Create a new key with the same scopes in the dashboard
2. Roll the new value into your env and redeploy
3. Wait until you see traffic on the new key (lastUsedAt updates on the list endpoint above)
4. Revoke the old key in the dashboard

Plan ahead. If step 3 is silent for hours, suspect a deploy issue before revoking.

Error codes

• unauthorized (401): the key is missing, revoked, or doesn’t match this organization
• forbidden (403): the key’s scopes don’t include the one this endpoint requires
• plan_limit_exceeded (403): your org hit its API-key cap; upgrade or revoke an unused key
• not_found (404): no key with that id in this org