An API token lets a script, a CI pipeline, the CLI or an AI assistant use the OpenWAF API on your behalf. Tokens look like owf_… and are sent as a bearer token:
GET /v1/orgs HTTP/1.1
Host: dash.openwaf.dev
Authorization: Bearer owf_…GET /v1/orgs returns the organization the token belongs to, with its id: the {org} of every other API path.
What a token is made of
| Property | Values | Notes |
|---|---|---|
| Name | 1–200 characters | Where it is used, for example “CI deploy”. |
| Role | owner, admin, tech, readonly | At most your own role. Defaults to your role. |
| Scope | Whole organization, one domain, or one client | Limit each token to what it needs. |
| Expiry | 1–365 days | Defaults to 90 days. There are no tokens without expiry. |
| Purge only | On or off | The token can only purge the cache of one domain. |
The secret is shown once, when the token is created. OpenWAF stores only a hash of it and shows a short prefix in the token list. If you lose a token, revoke it and create a new one.
Owner and effective role
Every token belongs to the member who created it and never does more than that member can do now:
- Its effective role is the lower of the token's role and the member's current role.
- If the member is limited to a client, the token is limited to that client too.
- If the member leaves or is removed from the organization, all their tokens are revoked.
See Effective role.
Scopes
- Whole organization: every domain of the organization, within the token's role.
- One domain: the token only sees that zone. It cannot add or delete domains, manage clients or create other tokens.
- One client: the token sees only the domains assigned to that client, and can only have the
techorreadonlyrole. Domains it adds are assigned to that client. - Purge only: a domain-scoped
techtoken that can only call the cache purge endpoints of its domain, for example from CI after a deploy. Any other call is refused with403 token_scope. See Cache.
Create a token
Open API tokens › Create token. Enter a name, choose the role, the scope and Expires in (days), and select Create token. Copy the secret from the dialog: it is not shown again.
curl -X POST "https://dash.openwaf.dev/v1/orgs/$ORG/tokens" \
-H "Authorization: Bearer $OPENWAF_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "CI deploy", "role": "tech", "zone_id": "'"$ZONE"'", "expires_in_days": 90}'The answer includes secret. Use client_id instead of zone_id to limit the token to a client, and "purge_only": true with a zone_id for a purge-only token.
Any member can create tokens for themselves. A domain-scoped token cannot create tokens.
List and revoke tokens
Admins of the whole organization see every active token in API tokens, with its scope, creator, expiry and last use, and can revoke any of them. Any token can revoke itself.
curl -X DELETE "https://dash.openwaf.dev/v1/orgs/$ORG/tokens/$TOKEN_ID" \
-H "Authorization: Bearer $OPENWAF_TOKEN"Revocation is immediate. Expired, revoked and unknown tokens get 401 unauthorized.
Tokens created by OAuth
When you connect an AI assistant to the MCP server with OAuth, OpenWAF creates a token for that connection. It appears in API tokens with the OAuth app badge; revoke it to disconnect the application.
Good practice
- Give each integration its own token, with the lowest role and the narrowest scope that works.
- Keep tokens in a secret store or an environment variable, never in a repository, a ticket or a command line. The CLI reads them from
OPENWAF_TOKENor a file inOPENWAF_TOKEN_FILE(readable only by you). - Prefer short expiries and rotate tokens before they expire.