API keys

API keys are created by a store owner (or a staff member with the right permission) from the dashboard. A key is shown once at creation — copy it then. A key is a single sk_ string (there is no separate live/test mode); only its first few characters are retained for display after creation.

Key kinds

Kind	Purpose	Scope
Integration	A machine integration or CI	Any subset of the store’s permissions you grant
Theme access	An outside theme developer / CI	Forced to themes only

A Theme Access key is a person-centric view over the same key system: it records the developer’s email and a default 30-day expiry, and the dashboard lists those keys as people (“Jane — Theme development — expires in 30d — Revoke”) separately from machine integration keys.

Scoping

Grant a key only the permissions it needs. Permissions mirror staff roles, so a key can be as narrow as “read products” or as broad as the owner allows — but a delegated key can never perform owner-only actions (activate/purchase/delete a theme), regardless of scope.

Using a key

Authorization: Bearer sk_xxxxxxxxxxxx

The key both authenticates and selects the store; you never pass a tenant id.

Rotation & revocation

• Rotate by creating a new key, deploying it, then revoking the old one.
• Revoke immediately if a key leaks — a revoked key returns 401 on the next request.
• Set an expiry for time-boxed access (a contractor, a one-off migration).

For CI

Provide the store and key by environment variable rather than an interactive login:

export CARTISTO_STORE_URL="https://acme.cartisto.app"
export CARTISTO_API_KEY="sk_xxxxxxxxxxxx"

The CLI reads these directly, so theme deploys run headless.