Docs

Authentication

The token header, the token format and every scope.

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.