Authentication

Every request to /api/v1/* (except /healthz and /openapi.json) requires a Bearer token. The v1 surface accepts the same personal API keys the MCP server uses — no separate provisioning, no separate scope model.

Sending the token

Authorization: Bearer fvk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Missing or invalid tokens produce a 401 UNAUTHORIZED. Expired or revoked keys return the same status.

Scopes

Scopes are attached when you create the key. The API enforces them at the endpoint level — a key without projects:write cannot call POST /projects. The supported scopes are:

• projects:read / projects:write — projects CRUD
• aso:read / aso:write — keywords, competitors, app metadata, charts
• store:read / store:write — listings, versions, reviews, review stats, localize
• screenshots:read / screenshots:write — screenshots, templates, Studio sessions
• review:simulate — read and trigger review simulations
• * — wildcard, grants all scopes (default for keys created without restriction)

Organization scoping

Each key is bound to the organization that was active when it was created. Project-scoped endpoints (/projects/:id/...) only return data for projects in that organization — a key from Org A can't reach Org B's projects, even if the user belongs to both.

Lifecycle

• Create — Account → API Keys → Create. Plaintext is shown once; copy immediately.
• Display — Only the prefix (fvk_live_abcd1234…) is stored unencrypted; the full key is hashed (SHA-256).
• Last used — last_used_at and last_used_ip updated on every authenticated request.
• Revoke — click Revoke on the dashboard. The key stops working immediately.
• Rotate — create a new key, swap in your secret store, then revoke the old one.

Storing keys

• Never commit a key to a repo. Use environment variables or a secret manager.
• Don't put keys in front-end code — fvk_live_* keys have full account access on whatever scopes are granted.
• Treat the prefix (fvk_live_xxxx) as semi-public; treat the full key as a password.