Skip to main content
Automation keys are live. Mint them under Settings → API Keys, or let an AI agent request one through the human-approved agent_auth device flow ("requested_key_type": "management" — see the agent authentication guide). Every grant is permission-scoped and can never exceed its approver’s own permissions.
VisIQ issues API keys in two audiences. Which one you need depends on what the key is for: If you are integrating the @visiq/harness SDK, you want a harness key — the dashboard studios mint one for you. This section is about the other audience: automation keys (also called management keys), which let your own automation call the VisIQ management API at https://api.visiqlabs.com.

​
What an automation key is

An automation key is a bearer credential for the management API:
Use it to script anything you could do in the dashboard — manage action-governance rules, register and update agents, query the audit log, respond to HITL items, or adjust settings — without a browser session. The two audiences are asymmetric. A harness key that tries to call a management endpoint is rejected with 403 harness_key_not_permitted, no matter what it is otherwise allowed to do. An automation key, by contrast, may call any endpoint its permissions allow — including the SDK operational endpoints.

​
The permission model

Every automation key carries an explicit list of permissions — the same resource:action catalogue that governs your team members (for example allow_rules:view, allow_agents:create, allow_audit_log:view). You pick the permissions when you create the key, grouped exactly as they appear in the team Roles matrix. Enforcement is exact and fail-closed:
  • A request is allowed only when the permission required by that route is in the key’s list. There is no wildcard expansion and no implication between permissions — allow_rules:view does not grant allow_rules:update.
  • Anything not explicitly granted is denied with 403 insufficient_permission. The response names the permission the route required and the permissions the key actually holds, so a denial is always diagnosable:
Grant the minimum set the job needs. A nightly job that pulls the action-governance audit log needs allow_audit_log:view — not Grant all.
Operational SDK routes. A management key is a superset of a harness key, so it can also reach the runtime endpoints. The evaluation legs — the unified POST /evaluate plus the per-plane POST /allow/evaluate and POST /recall/evaluate — are gated by coarse product scopes: a management key holding a …:write-class permission for a product derives the matching write scope and can evaluate through it. Two runtime routes require an explicit permission on top: record envelope ingestion (POST /record/envelopes) also requires record_records:create, and writing agent attribution (POST /allow/agents/register) also requires allow_agents:create. If you only want a key to reach the management API (rules, agents, audit) and never the evaluate path, grant read-class permissions — they do not derive the write scopes that open the operational routes.
Legacy scoped keys still work. Keys created before explicit permissions shipped carry coarse scopes instead of a permission list. The scope vocabulary is the per-product pairs allow:read/allow:write, recall:read/recall:write, record:read/record:write, the unified rules:read/rules:write/rules:evaluate (the unified read and write scopes subsume their per-product counterparts; rules:evaluate is evaluation-only and never satisfies a rule-management gate), and full_access. Scoped keys are still honored under the original scope-mapping rules, and a scope denial returns 403 insufficient_scope. New automation keys always use explicit permissions.

​
Built-in guardrails

Automation keys ship with the security properties a credential system should have, on by default:
  • Privilege-bound minting — a key can never be created with permissions its creator does not hold. The request is rejected with 403 and the list of exceeded permissions, so a narrowly-permissioned caller cannot bootstrap a stronger key.
  • Audited lifecycle — every create, rotate, and revoke is written to your tenant audit log; key creation and rotation abort (rolling back the new secret) if the audit write fails. There is no unaudited key event.
  • Hashed at rest — VisIQ stores only a SHA-256 hash of each key and verifies it with a timing-safe comparison. The plaintext is shown exactly once, at creation.
  • Fail-closed authentication — expired keys (including a lapsed rotation grace window) stop authenticating immediately, and every key is rate limited with a per-key sliding window.

​
Where to create one

Open Settings → API Keys and click Create New Key — naming the key, picking its environment and expiry, and selecting its permissions. The full key is shown exactly once. AI agents can instead self-register via the agent_auth device flow and receive a management key after human approval. See the managing keys guide for the complete flow, rotation, rate limits, and error reference.

Managing automation keys

Creation flow, key format, expiry, rotation with grace windows, rate limits, and error codes.

Action Governance API

The management endpoints for rules, agents, audit log, HITL, and settings.