Skip to main content
Automation keys authenticate your scripts and CI against the VisIQ management API. This page covers their full lifecycle. For what automation keys are and how the permission model works, start with the Platform Automation introduction.
Agents can obtain automation keys too. Besides the dashboard flow below, an AI agent can self-register through the agent_auth device flow with "requested_key_type": "management" and an explicit permission list; a human reviews the exact grant at /agent/claim and approves or narrows it. The grant can never exceed the approver’s own permissions. See the agent authentication guide.

​
Create a key

  1. In the dashboard, open Settings → API Keys.
  2. Click Create New Key (requires the api_keys:create permission).
  3. Fill in the dialog:
    • Name — a label for the key (1–50 characters), e.g. ci-audit-export.
    • Environment — production or test. This only determines the key prefix (vq_prod_ vs vq_test_) so you can tell credentials apart.
    • Expires — 30 days, 90 days (default), 180 days, 1 year, or No expiry. Prefer an expiry; expired keys stop authenticating automatically.
    • Permissions — pick the explicit permissions the key needs, grouped the same way as the team Roles matrix. Each group has a select-all checkbox, and Grant all selects everything — use it sparingly.
  4. The full key is displayed exactly once — copy it into your secrets manager immediately.
You can only grant permissions you hold yourself. A request for anything beyond your own effective permissions is rejected with 403 and an exceededPermissions list — no key can be more powerful than its creator. Every creation is recorded in your audit log as API_KEY_CREATED, and the operation aborts if the audit write fails.
The plaintext key is shown only at creation (and rotation). VisIQ stores a SHA-256 hash — verified with a timing-safe comparison — never the key itself. If you lose it, rotate or re-create the key. Never commit keys to source control.

​
Key format

A vq_prod_ / vq_test_ prefix followed by 64 hex characters. The dashboard key table shows only the first 16 characters (vq_prod_f3a91c0e****) so you can identify a key without exposing it.

​
Use a key

Send it as a bearer token to https://api.visiqlabs.com:
The request succeeds when the route’s required permission is in the key’s permission list — this example needs allow_audit_log:view — otherwise it is denied (see Errors). Every authenticated request updates the key’s Last Used timestamp, shown in the dashboard key table. Use it to spot stale keys and revoke them before they become forgotten liabilities.

​
Rotate a key

Rotation issues a new secret for the same logical key — name, environment, permissions, audience, and expiry all carry over — and retires the old one. In the key table, open the row’s actions menu and choose Rotate Key (requires api_keys:rotate). The rotation dialog asks how long to keep the old key valid — the grace window: Revoke immediately, 1 hour, 24 hours (default), or 7 days.
  • The new key is returned once, exactly like at creation.
  • The old key keeps authenticating until the grace window lapses, so in-flight callers can cut over with zero downtime. The table shows the retiring row as Grace ends in ….
  • With Revoke immediately, the old key stops authenticating at once.
  • Once the grace window lapses the old key returns 401 API key has expired.
  • The retired key is linked to its replacement (replaced_by_key_id), so the rotation chain is auditable, and the rotation itself is logged as API_KEY_ROTATED. If the audit write fails, the new key is rolled back — a rotation never leaves an unaudited live secret behind.
Rotate-with-grace means two valid secrets exist for the duration of the window. Pick Revoke immediately when you suspect the old key is compromised — grace is for routine credential hygiene, not incident response.

​
Revoke a key

Revocation is available today, including for existing automation keys. Choose Delete Key in the row’s actions menu (requires api_keys:delete) and confirm. Revocation is immediate — the very next request with that key receives 401 — and is logged as API_KEY_REVOKED. There is no grace window and no undo; create a new key if you revoked the wrong one.

​
Revoke your own key (self-revocation)

Beyond the dashboard, the holder of a key can always revoke that key itself — no dashboard, no human, and no special permission (RFC 7009 spirit). This is the clean way for an automation or agent to end its own session or retire a credential it believes is compromised, and it is the only revoke path a permission-scoped key can rely on (such a key may not hold api_keys:delete). The endpoint is authenticated by the presenting key itself — the credential is resolved from its own bearer token, so the only key it can ever target is the caller’s own. There is no request body naming another key, which makes cross-key revocation impossible through this path.
The same operation is exposed on the web JSON API at POST https://app.visiqlabs.com/api/allow/self/revoke, and as the revoke_self tool on the Platform MCP server (no arguments).
Self-revocation is immediate, idempotent, and irreversible. After it succeeds the key stops authenticating at once, so it must be the last call you make with that key. A key that is already revoked, unknown, or expired returns 401; a dashboard user session (not an API key) returns 400 not_an_api_key. Legacy vendor root keys have no api_keys row and are not self-revocable — rotate them from the dashboard instead.
Agents that obtained their key through the device flow can also tear it down (including a still-pending registration) via POST /api/agent/identity/revoke.

​
Expiry

A key with an expiry stops authenticating the moment expires_at passes — requests receive 401 API key has expired. The dashboard shows expiry as in 12d / Never / Expired. Expiry cannot be edited after creation, and a rotated key’s replacement inherits the original expiry — to extend a key’s life, create a new key.

​
Rate limits

API-key requests are rate limited per key with a sliding window — 600 requests per minute by default. Every authenticated response carries the current state: Exceeding the limit returns 429 Too Many Requests with a Retry-After header (seconds until the window frees up):
Back off for Retry-After seconds before retrying. Dashboard sessions are not subject to this limit — it applies to API-key traffic only. The limiter is fail-closed: if it cannot be evaluated, the request is denied rather than waved through.

​
Errors

A 403 insufficient_permission response tells you exactly what was missing:
Fix it by creating a key that includes the requiredPermission — permissions cannot be edited on an existing key.
403 insufficient_scope comes from the coarse scope layer. You will see it most often on legacy keys created before explicit permissions shipped, but any key whose (derived) scopes do not cover a scope-gated route — the evaluation endpoints, for example — receives it too. Permission denials on permission-gated routes return insufficient_permission instead.