API tokens
Least-privilege tokens for the CLI, CI and your servers - permissions, resources, client IP filter, expiry, roll and revoke.
Every call to the BWEZE API carries a token:
curl https://api.bweze.com/v1/me -H "authorization: Bearer bw_sk_..."A token does only what you granted it, on the resources you gave it, from the addresses you allow, while it is valid - and never more than its owner's role in the workspace. Make one per job (a CI pipeline, a server that sends SMS, a script that edits DNS) so each can be narrowed, rolled or revoked on its own.
Manage them in BWEZE Platform under Manage workspace › API tokens.
Create a token
-
Start from a template, or a blank custom token:
Template Grants Read everything deployment:read,backend:read,dns:read,message:readDeploy from CI deployment:read,create,update,backend:read,createDNS editor dns:read,create,update,deleteSend SMS message:read,send -
Permissions and limits. Name it, choose its owner and type, then:
- Permissions, per product: no access, read, or edit (send for SMS, run commands for Terminal). Open a product to pick single actions. Anything your role cannot do is shown but locked.
- Resources: all projects, backends and DNS zones, or only the ones you tick. A token limited to some projects cannot create new projects; the same goes for backends and zones.
- Client IP filter: IPv4 and IPv6 addresses or ranges, one per line. Empty allows any address.
- Validity: an expiry (30 days, 90 days, 1 year, a date, or none) and optionally a start time.
-
Review the summary and create it. The secret is shown once - BWEZE keeps only a hash.
Permissions
| Product | Actions | What they allow |
|---|---|---|
Deploy (deployment) | read create update delete | Projects, services and their settings (update), job runs (read), cron jobs, firewall rules, analytics |
Backends (backend) | read create delete | Backend stacks; create also starts them and reads their connection keys |
Domains and DNS (dns) | read create update delete | Zones and records, custom domains, domain search and registration |
SMS (message) | read send | Previews; sending is charged to the wallet |
Terminal (terminal) | exec | Run commands in a project's container, and run or stop one-off jobs on a service |
Tokens can never manage the workspace, its members, billing or other tokens.
Publishable tokens (bw_pk_...) are for browsers and apps: they can only read.
Who a token belongs to
- You (the default): it can never do more than your current role allows.
Each request checks the token's grant and your live role, so if you are
demoted it loses those rights on the next request, and if you leave the
workspace it stops working (
token_owner_removed). - The workspace: for automation that must outlive any one person. It keeps working when people leave. Only owners can create, widen or roll one, and it is capped by the owner role.
Change, roll and revoke
Open a token to see what it can do, when it was last used and from where, and its activity: every create, edit, roll and revoke, with who did it.
- Edit: narrowing (fewer permissions or resources, a tighter IP filter, an earlier expiry) is open to the token's owner and to workspace owners and admins. Widening takes what creating takes: only the token's owner, within their role (owners, for a workspace token).
- Roll: a new secret with the same permissions; the old secret stops working at once.
- Revoke: the token stops working at once and stays listed as revoked.
Check a token
GET /v1/me returns the token's workspace, owner, permissions, resource scope
and expiry:
{
"keyName": "GitHub Actions deploy",
"tokenId": "6f1c…",
"organizationId": "…",
"ownerKind": "user",
"role": "developer",
"tier": "secret",
"permissions": { "deployment": ["read", "create", "update"], "backend": ["read", "create"] },
"scope": { "projects": ["…"], "backends": null, "zones": null },
"expiresAt": "2027-11-14T12:00:00.000Z"
}null in scope means every resource of that kind.
Errors
None of these succeed on retry: change the token, or use another one.
| Code | Status | Meaning |
|---|---|---|
token_ip_denied | 403 | The request came from an address outside the token's IP filter |
token_not_yet_valid | 401 | Before the token's start time |
token_expired | 401 | After the token's expiry |
token_owner_removed | 403 | The member who owns the token left the workspace |
token_permission_denied | 403 | The token was not granted this action |
key_role_denied | 403 | The token was granted it, but its owner's role no longer allows it |
token_resource_denied | 403 | The project, backend or zone is outside the token's resources, or a scoped token tried to create one |
token_policy_missing | 401 | The key has no token policy; create a new token |
publishable_key_write_denied | 403 | A bw_pk_ token tried to change something |
How the client IP is known
api.bweze.com is served through Cloudflare. Cloudflare's edge sets the
CF-Connecting-IP header to the address that connected to it and replaces any
value a client sends, so it cannot be forged through the edge. BWEZE checks the
IP filter against that address only, never X-Forwarded-For. A request that
reaches BWEZE without a trusted address is refused by any token that has an IP
filter.