API keys and public API v1

Simple terms

API keys let external servers automate Apex safely for a shop.

Lets external systems create and manage experiments, variations, goals, screenshots, webhooks, privacy requests, and harness sessions.

Routes

• /api-keys
• /api/v1/*

Implementation behavior

• API keys are created per shop as publishable, test secret, or live secret keys and stored hashed.
• Secret keys are shown once, then used as bearer tokens for /api/v1 requests.
• Public route handlers validate the key, resolve the shop, authorize the action, and return JSON responses.
• The docs page renders the OpenAPI reference from the app's openapiSpec source.

How to use it

• Create a live secret key for production server-to-server automation.
• Use test secret keys for staging and automation trials.
• Never put secret keys in browser code; use publishable keys only where client exposure is intended.
• Use the OpenAPI reference for request and response shapes.

When not to use it

• Do not put live secret keys in browser code, snippets, or public repositories.
• Do not use a live key for staging automation.
• Do not keep unused keys active after an integration is removed.

Implementation source

• UI lives under src/app/(dashboard)/api-keys.
• Handlers live under /api/api-keys and /api/v1/*.
• OpenAPI source lives in src/lib/api/openapi-spec and schemas live under src/lib/api.

Data and API

• Prisma ApiKey with hashed secret, type, permissions, expiry, and shop relation.
• APIs: /api/api-keys and all /api/v1/* handlers.
• OpenAPI JSON at /api/v1/openapi.json.

Failure modes

• 401 or 403: missing bearer token, wrong key type, expired key, disabled key, or wrong shop.
• Lost secret: create a new key because full secrets are not recoverable.
• Automation mutates wrong shop: verify key belongs to the intended active shop.