Authentication

API keys for your own backend, OAuth for apps acting on a merchant's behalf, and the scope algebra both share.

Version v1 · updated 2026-02-01

There are exactly two ways to authenticate. Which one is correct is decided by a single question: does the credential belong to you, or to a merchant who has to consent to what you do with it?

API keys#

Send the key as a bearer token. Framique stores only a hash, so a lost key cannot be recovered — it is rotated. Rotation issues a second live key so you can deploy before revoking the first.

GET /api/public/v1/products?limit=25 HTTP/1.1
Host: your-store.framique.com
Authorization: Bearer fq_live_9f2c…
Accept: application/json

OAuth 2.0 with PKCE#

Public clients (CLI tools, single-page apps) must use PKCE; there is no implicit flow and no client secret in a browser. Authorization codes are single-use and expire in 60 seconds, and a reused code revokes the whole grant family — a replayed code is treated as theft, not as a retry.

curl -s -X POST "https://api.framique.com/api/public/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "'"$CODE"'",
    "client_id": "'"$CLIENT_ID"'",
    "code_verifier": "'"$VERIFIER"'",
    "redirect_uri": "https://app.example.com/callback"
  }'

Scopes#

Scopes are the same catalogue everywhere: the consent screen, the key editor and the gateway authorizer all read one table, so a scope cannot mean one thing on screen and another at the door. A `.write` scope implies `.read` of the same resource and nothing else.