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.