Every request needs a token in the Authorization header.
curl https://app.shopbird.app/api/v1/locks \
-H "Authorization: Bearer sb_live_…"
Shopbird ignores a token in the query string. A request without a valid token gets 401 unauthorized.
Tokens
| Fact | Value |
|---|---|
| Where to create one | Settings > API access |
| Format | sb_live_ and a random string |
| Shown | Once, when you create it. Shopbird keeps only a hash. |
| Revoke | Any time, in Settings. Anything using the token stops at once. |
| Activity | Each token has a page listing its requests for the last 30 days. |
Scopes
Pick scopes when you create a token. A route that needs a scope the token lacks answers 403 insufficient_scope:
{ "status": 403, "code": "insufficient_scope", "required_scope": "locks:write", "request_id": "…" }
| Scope | Lets the token |
|---|---|
locks:read |
See locks |
locks:write |
Edit locks |
audiences:read |
See audiences |
audiences:write |
Edit audiences |
codes:read |
See codes |
codes:write |
Create and revoke codes |
drops:read |
See drops |
drops:write |
Edit drops and draw raffles |
customers:write |
Tag customers |
settings:read |
See settings |
settings:write |
Edit settings |
sync:write |
Start syncs |
access:read |
Check who can unlock |
webhooks:read |
See webhook endpoints and deliveries |
GET /api/v1/sync works with any valid token.
Scopes that grant access
These scopes can let shoppers buy or reveal working codes. Settings marks them. Give them only to systems you trust.
| Scope | Why |
|---|---|
locks:write |
It can turn a lock off or change who it lets in. |
audiences:write |
It can change who an audience lets in. |
codes:read |
It returns working codes. |
codes:write |
It creates codes. |
customers:write |
It adds the tags that tag audiences let in. |
drops:write |
It can change a drop's early access and selling. |
What no token can do
No token can do these. They stay in Settings.
- Create tokens.
- Manage webhook endpoints.
- See webhook secrets.