The customer API authenticates with a Bearer token. You create a key in the dashboard, store it like any other secret, and send it on every request:
Authorization: Bearer qu_live_AbCdEf...API access is a Pro and Team feature. Free plans cannot mint keys.
Create a key
- Open Dashboard → API keys (admin only).
- Click Create key, give it a memorable name (e.g.
crm-sync,staging-deploy). - The full key is shown exactly once. Copy it into a secrets manager or environment variable.
- The list page only shows the prefix from this point on; the full value is unrecoverable.
A typical key looks like qu_live_AbCdEfGh23456789.... The leading qu_live_ prefix lets you grep for accidental leaks and is recognised by GitHub secret scanning.
Send a request
curl -H "Authorization: Bearer qu_live_AbCdEf..." \
"https://api.getqueueup.com/v1/api/waitlists/wl_abc123/subscribers?limit=50"Every endpoint under /v1/api/* accepts the same Bearer header. The key resolves to the organisation it was created in; you cannot read or write data for any other tenant.
Scopes
Every key carries a list of scopes that decide which endpoints it can call. Pick scopes when you create the key in the dashboard. Today’s scopes:
| Scope | Grants |
|---|---|
subscribers:read | GET /v1/api/waitlists/{id}/subscribers |
subscribers:write | POST /v1/api/waitlists/{id}/subscribers |
The dashboard offers two presets: Full access (both scopes) and Read-only (just subscribers:read). Read-only is the right choice for analytics jobs, CSV exports, or anything that pulls data into a frontend bundle where the key might end up close to your customers’ eyes.
A request hitting an endpoint your key isn’t scoped for returns 403 insufficient_scope. Recovery is a matter of minting a new key with the right scopes and revoking the old one; scopes on an existing key are immutable.
Errors
| Status | When |
|---|---|
401 unauthorized | Header missing, malformed, key unknown, or key revoked. (We collapse all four so probing can’t distinguish.) |
403 feature_not_allowed | Tenant downgraded to a plan that no longer grants API access. Existing keys stay in the table; restoring the plan re-enables them without re-creation. |
403 insufficient_scope | Key authenticated but doesn’t carry the scope this endpoint requires. The response body’s message names the missing scope. |
429 rate_limit_exceeded | This key has exceeded its per-minute budget. Honour the Retry-After header. |
Rate limits
Each key has its own budget, independent of the public widget’s per-IP throttle. Defaults to 60 requests / minute / key. If you need more, get in touch.
Rotation
Keys are immutable. To rotate, create a new key, deploy it, then revoke the old one from the dashboard. Revocation is immediate; any service still using the old key will start receiving 401 on the next request.
Audit trail
Every key creation and revocation is recorded in the Activity log with the operator who performed it. Mutations made through a key (server-side subscribes, future write endpoints) are recorded with the key’s display name as the actor, so you can attribute server-to-server traffic to a specific integration.