Authentication
Create API keys, choose scopes and store restrictions, use test keys and rotate keys safely.
Send your key in the Authorization header:
Authorization: Bearer sa_live_AbCdEfGhIjKl_0123456789abcdefghijklmnopqrstuvKeys look like sa_live_<prefix>_<secret> or sa_test_<prefix>_<secret>. A missing, malformed, revoked or expired key gets 401 unauthenticated.
Create a key
Owners and admins create keys under Developers → API keys (recent sign-in and a verified email required):
- Choose the scopes.
- Optionally restrict the key to some stores. A restricted key sees only those stores everywhere, including the event log; other stores answer
404. - Choose an expiry (default 1 year, at most 2 years).
- Copy the key. It is shown once; ShopAssist stores only a hash. Owners get an email for every new key.
Scopes
| Scope | Grants | Plan |
|---|---|---|
stores:read | list and read stores | every plan |
conversations:read | conversations, messages, handoffs, CSAT, AI content verification | API read access |
conversations:write | delete conversations | full API access |
leads:read | leads with consent records | API read access |
leads:write | delete leads | full API access |
engagement:read | back-in-stock subscriptions | API read access |
analytics:read | analytics overview and time series | API read access |
knowledge:read | knowledge documents | API read access |
knowledge:write | upsert and delete FAQs | full API access |
catalog:write | Catalog Push API | every plan |
orders:report | order reports for attribution | every plan |
privacy:write | privacy requests | every plan |
events:read | event log | API read access |
A request without the required scope gets 403 forbidden with details.required_scope. Plan access is checked on every request: after a downgrade, keys with scopes your plan no longer includes get 403 plan_feature_unavailable at once.
Test keys
sa_test_… keys are read-only development keys against your live data: they may hold only *:read scopes, are limited to 60 requests per minute, and write endpoints answer 403 forbidden with details.reason = "test_key".
Rotating and revoking
Keys have a single secret. To rotate: create a new key, deploy it, check that Last used of the old key stops changing, then delete the old key. Deleting a key takes effect within 60 seconds.
Keep keys on the server
Never put an API key in browser code, a mobile app or a public repository. If a key leaks, delete it immediately and create a new one.
Last updated on