> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visiqlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Platform Automation
> Automate the VisIQ management API from scripts and CI with permission-scoped automation keys.
**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](https://visiqlabs.com/auth.md)). 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:
| | Harness keys | Automation keys |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| **Who uses it** | The SDK / harness / agents at runtime | Your scripts, CI pipelines, and back-office tooling |
| **What it can reach** | The SDK operational endpoints only (evaluation — unified and per-plane — rule bundles, HITL decision polling, telemetry, record envelope ingestion, agent registration, discovery sensor reporting) | The management API — rules, agents, audit log, settings, and more |
| **How access is scoped** | Not scoped — full power within its route allowlist, denied everywhere else | An explicit permission list you choose at creation |
| **Where to create one** | **Settings → Harness Keys** (or minted automatically by the SDK install studios and agent registration) | **Settings → API Keys**, or agent self-registration via the `agent_auth` device flow |
If you are integrating the `@visiq/harness` SDK, you want a
[harness key](/quickstart) — 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:
```bash theme={null}
curl https://api.visiqlabs.com/allow/rules \
-H "Authorization: Bearer vq_prod_..."
```
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:
```json theme={null}
{
"error": "insufficient_permission",
"detail": "This management API key is not granted the requested permission.",
"requiredPermission": "allow_rules:update",
"grantedPermissions": ["allow_rules:view", "allow_audit_log:view"]
}
```
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](/automation/api-keys#rate-limits) 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](/automation/api-keys) for the complete flow,
rotation, rate limits, and error reference.
Creation flow, key format, expiry, rotation with grace windows, rate
limits, and error codes.
The management endpoints for rules, agents, audit log, HITL, and settings.