Developers & AI
API keys and OAuth scopes
Bearer tokens (eta_…) and API keys (etsk_live_…). Scopes limit what an agent can do.
Every Developer API and MCP request needs Authorization: Bearer <token>. Two credential types work: OAuth access tokens (eta_…) from the authorize/token flow, and API keys (etsk_live_…) created in the console.
Both are bound to one store at grant/create time. Do not send storeId as a client parameter — the server uses the credential’s store. Trying another store’s IDs returns NOT_FOUND.
Create an API key from an expanded app → Create API key. The full secret is shown once. Name keys by purpose (for example Agent key). Rotate replaces the secret; revoke disables it immediately.
Default theme-AI scopes (publish opt-in): store:read, products:read, collections:read, settings:read, themes:read, themes:create, themes:write, themes:preview, pages:read, pages:write, media:read, media:write, navigation:read, navigation:write.
What scopes mean in practice: store:read — profile and branding; products:read / collections:read — catalog for design context; themes:* — draft and preview work; pages:* / media:* / navigation:* — supporting presentation; themes:publish — go live (keep off for AI).
Optional read scopes for richer agents: orders:read, customers:read, checkout:read — still no commerce mutations through the developer API for AI workflows.
Errors: INSUFFICIENT_SCOPE when a tool needs a scope you did not grant; UNAUTHORIZED when the token is missing or revoked; NOT_FOUND for wrong-tenant resources (intentional — no IDOR leakage).
REST lives under /api/v1 with standard envelopes, cursor pagination, and idempotency where documented. OpenAPI: /developers/openapi.json .
Rotate keys if they appear in logs or chat. After rotate, update Claude/Cursor/env vars. Revoke unused keys. Regenerate OAuth client secrets the same way if leaked.
More: /developers/authentication , /developers/api , and the console app detail panel for live keys and grants.
Was this article helpful?
Contact support