Home Features Pricing App AI Advisor Docs Compare About Training Contact Log In Get an API key
Developersv1.0.0-rc.6
Browse the guides

Start here

Getting StartedAuthentication & API KeysScopes

Working with the API

Requests & ResponsesPagination, Filtering & SyncWorkflow States & ActionsErrors & Workflow BlockersIdempotency & ConcurrencyRate Limits

Events

Webhooks

Integrating

External ReferencesVersioning & DeprecationExample IntegrationsAI-Agent Guide

Reference

API Reference
Developers/Start here

Authentication & API Keys

Bearer keys issued per integration by the shop; revocation is immediate; secrets are never retrievable.

Every request carries an API key as a bearer token:

GET /v1/customers HTTP/1.1
Host: api.shopcommander.com
Authorization: Bearer sc_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Keys start with sc_live_. Only a SHA-256 hash is stored; the plaintext is shown to the shop once when the key is issued and cannot be recovered. The API never uses cookies or sessions and never accepts a key in the query string.

Integrations, keys, and shops

  • An integration is the principal: it belongs to exactly one shop, holds a set of scopes, and owns its keys and webhook endpoints.
  • A key is a time-bounded credential for its integration. New keys expire in 1–365 days (90 days by default). An integration can hold two usable keys so a rotation can overlap: issue the new key, switch your caller, revoke the old one. Treat api_key_expired as a non-retryable authentication failure and ask the shop to issue a replacement.
  • Keys share their integration's rate limit; integrations share the shop's ceiling. Creating more keys never buys more throughput.
  • One key reaches one shop. A vendor serving many shops holds one key per shop, granted by each shop.

Revocation

Revoking a key or an integration takes effect on the next request — authority is the database row, not a cached token. A revoked key returns 401 authentication / invalid_api_key; a suspended integration returns 403 permission / integration_suspended.

Authentication errors

Status code Meaning
401 missing_api_key No Authorization: Bearer header
401 invalid_api_key Unknown, malformed, or revoked key
403 integration_suspended Platform operators suspended the integration (reason shown to the shop)
403 shop_inactive The shop's Shop Commander account is inactive
403 insufficient_scope Valid key, but the integration lacks the scope — details.required_scope names it
503 public_api_disabled / public_api_writes_disabled A platform kill switch is on; retry later

All errors use the error envelope.

Keep keys safe

  • Store keys in a secrets manager or environment variable, never in source control or a browser bundle.
  • Use one integration per system so a compromise is contained and the shop can see, in its activity log, which system did what.
  • If a key leaks: the shop revokes it in Settings → Developer, issues a replacement, and reviews the integration's activity and the audit history. Every change made through the API is attributed to the integration by name in the shop's audit trail.
Previous← Getting Started NextScopes →