Back to zillo.app

Authentication

The Zillo API accepts two auth shapes: scoped API keys and OAuth access tokens.

The API, webhooks, and MCP server are part of Zillo Pro, the store's optional add-on. Calls from a store without Pro return 402 pro_required. Stores that were already using the API or webhooks before Pro launched keep their access.

API keys

Bearer tokens minted from Developers → API keys. The format is zk_<mode>_<secret> with mode being test or live.

Authorization: Bearer zk_live_A7vXm2KZc9nQbHy3LpRfTuG8sJWdoYxN
  • Plaintext shown exactly once at creation.
  • We store only sha256(plaintext).
  • Revoking takes effect immediately.
  • Each key carries a fixed set of scopes — see Scopes.

Test vs live mode

A zk_test_* key only operates when your store is in test mode. A zk_live_* key only operates against live data. Cross-mode use returns 403 wrong_mode.

Scopes

Scopes are resource:action pairs. A key can do exactly what its scopes allow, nothing more. Resources:

  • products:read | write
  • orders:read | write
  • customers:read | write
  • gift_cards:read | write | redeem
  • tickets:read | write | redeem
  • bookings:read | write | redeem
  • vouchers:read | write | redeem
  • memberships:read | write | checkin
  • webhooks:read | write

The * super-scope grants everything and requires the merchant to confirm-by-typing their store slug.

IP allowlist

Optionally restrict a key to a list of CIDRs. Requests from outside the allowlist return 403 ip_not_allowed.

OAuth 2.0 (for MCP)

When an MCP client (Claude, Cursor, Zed, Continue, Goose, etc.) connects to the Zillo MCP server, it uses OAuth 2.0 + PKCE to mint a scoped access token (1h) + refresh token (30d). The token endpoint is https://api.zillo.app/oauth/token; metadata at https://api.zillo.app/.well-known/oauth-authorization-server.

Leaked-key auto-revoke

We're registered with GitHub's secret-scanning partner program. If a Zillo API key is pushed to a public GitHub repo, we'll auto-revoke it and email the merchant within minutes.