API tokens

Create a token

1. 1.Open Account → Developer → API tokens.
2. 2.Enter a name that says where it will be used, for example github-actions or prometheus, tick the scopes it needs (read metrics, deploy, ops hub), choose an expiry (30 days, 90 days, 1 year or never) and click Create token.
3. 3.Copy the value now. It starts with opv_ and is shown only once; Opservo stores a hash, not the token.

The list shows each token’s name, its first characters, its scopes, when it expires and when it was last used, so you can tell which ones are still in use. Only workspace owners and admins can create or revoke tokens, and creating one asks you to confirm your identity when the workspace requires that; read-only demo and impersonation sessions cannot.

Scopes and expiry

A call outside the token’s scopes returns HTTP 403 with missing_scope naming the scope it lacks. An expired token returns 401 like a revoked one; create a new token before the old one runs out. Tokens created before 16 October 2026 have every scope and no expiry; they are marked in the list so you can replace them with narrower ones.

Revoke a token

Click Revoke next to the token. Anything using it gets HTTP 401 on its next request. There is no undo; create a new token instead.

How to send it

Either header works:

Authorization: Bearer opv_…
# or
X-Opservo-Token: opv_…

A token is bound to the workspace it was created in and stops working if the workspace is suspended. It has no per-user identity; audit entries record the token name as the actor and the token id in the detail. A token is not subject to the dashboard’s screen lock or step-up confirmation, which is why minting one requires them.

Which endpoints accept a token

Every other endpoint, including the server list and the alert, incident and command routes, needs a dashboard session. Tokens are for exporting metrics, push-to-deploy and MCP, not a general-purpose API key.

Examples

curl -s https://api.getopservo.com/api/v1/metrics/catalogue \
  -H "Authorization: Bearer $OPSERVO_TOKEN" | jq '.metrics[] | {key, unit, group}'

curl -s "https://api.getopservo.com/api/v1/metrics/query?metrics=cpu_percent,mem_percent&hours=24" \
  -H "Authorization: Bearer $OPSERVO_TOKEN"

curl -s -X POST https://api.getopservo.com/api/v1/agents/<agent-id>/deploy \
  -H "X-Opservo-Token: $OPSERVO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ref": "'"${GITHUB_SHA:-manual}"'"}'

The agent id is the id in the server page URL. The query endpoint returns, per metric and per server, a list of {t, v} points plus bucket_seconds so you know the resolution.

Keep tokens safe

• •Store tokens in your CI secret store or Grafana’s encrypted settings, never in a repository.
• •Use one token per consumer so you can revoke one without breaking the others.
• •A deploy triggered with a token runs on the server only if remote actions are enabled there; see Remote actions.