BWEZE Docs

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

  1. Start from a template, or a blank custom token:

    TemplateGrants
    Read everythingdeployment:read, backend:read, dns:read, message:read
    Deploy from CIdeployment:read,create,update, backend:read,create
    DNS editordns:read,create,update,delete
    Send SMSmessage:read,send
  2. 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.
  3. Review the summary and create it. The secret is shown once - BWEZE keeps only a hash.

Permissions

ProductActionsWhat they allow
Deploy (deployment)read create update deleteProjects, services and their settings (update), job runs (read), cron jobs, firewall rules, analytics
Backends (backend)read create deleteBackend stacks; create also starts them and reads their connection keys
Domains and DNS (dns)read create update deleteZones and records, custom domains, domain search and registration
SMS (message)read sendPreviews; sending is charged to the wallet
Terminal (terminal)execRun 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.

CodeStatusMeaning
token_ip_denied403The request came from an address outside the token's IP filter
token_not_yet_valid401Before the token's start time
token_expired401After the token's expiry
token_owner_removed403The member who owns the token left the workspace
token_permission_denied403The token was not granted this action
key_role_denied403The token was granted it, but its owner's role no longer allows it
token_resource_denied403The project, backend or zone is outside the token's resources, or a scoped token tried to create one
token_policy_missing401The key has no token policy; create a new token
publishable_key_write_denied403A 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.

On this page