Guides

Create and manage API tokens

Issue personal access tokens for scripted access to the HowlOps REST API.

On this page

Create a token
Use a token
Revoke a token
List and audit tokens
Token scopes
If a scripting token needs more than the default
Token limit
See also

API tokens let scripts, CI pipelines, and external tools authenticate against the HowlOps REST API without using your password.

Create a token

Go to Settings → API tokens.
Click New token.
Enter a descriptive name (for example: ci-pipeline or monitoring-script).
Choose the scopes with the read / write chips (see Token scopes below).
Click Create.

Copy the token now. It is shown only once. If you lose it, revoke it and create a new one.

The token starts with howlops_ followed by a 64-character hex string. Tokens created from the UI do not expire; revoke a token when you no longer need it.

Use a token

Pass the token as a Bearer token in the Authorization header:

bash

curl -X GET https://api.example.com/api/v1/monitors \
  -H "Authorization: Bearer howlops_abc123..."

All API endpoints that require authentication accept this token. See the REST API reference for a full endpoint listing.

Revoke a token

Go to Settings → API tokens.
Find the token row.
Click the action menu (...) > Revoke.

The token becomes invalid immediately. There is no recovery; create a new token if needed.

List and audit tokens

The API tokens list shows every active token along with:

Name
Permissions (scopes)
Created date
Last used date (updated best-effort on each request)
Expiry date (UI-created tokens show "Never")

If a token has not been used in a long time, consider revoking it to reduce attack surface.

Token scopes

Every token carries one or more scopes that bound the category of endpoint it may call:

Scope	Grants
`read`	Read-only access to your resources (GET endpoints).
`write`	Allows POST/PUT/PATCH/DELETE requests.
`metrics`	Access to metrics ingestion endpoints.
`admin`	Enables narrow workspace-automation routes when the token owner is currently an owner or admin. It never grants billing, token-minting, or platform-admin access.

Write operations require a token that includes the write scope (or admin); a read-only token is rejected on any mutating request. The New token form has read and write scope chips; pick both if your script needs to create, update, or delete resources. The form defaults to read.

A scripting token normally remains capped at the API-token permission set. For infrastructure automation, an admin token whose owner is currently a workspace owner or admin may call only explicitly allow-listed workspace configuration routes, such as team and member notification-policy management. The role is checked on every request and authority disappears when the owner loses it. The token cannot manage billing, mint tokens, switch tenants, or access platform administration. A mobile token acts with its owner's current role because it represents an interactive device session.

If a scripting token needs more than the default

Use admin only for workspace-as-code tooling that needs those allow-listed routes. Prefer read and write for monitor-only automation. The live owner-role check immediately narrows existing tokens when a role is removed.

If your integration genuinely needs elevated access — for example, to delete notification channels or edit billing — invite a dedicated account for it (a service or bot email address you control) with a custom role that grants exactly the permissions the integration needs, then create the API token from that account instead of the owner's. This keeps the elevated access scoped to one identifiable, revocable account rather than tied to the owner.

Token limit

The number of active API tokens is capped per plan (max_api_tokens from your capability plan). Attempting to create a token beyond the cap returns a limit error: revoke an unused token or upgrade the plan to raise the ceiling. Mobile app device tokens do not count toward this cap.