> ## 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.
# Authentication
> The canonical guide to VisIQ credentials — the two key audiences (harness vs management), permissions and scopes, rotation, self-revocation, the agent device flow, and MCP.
Every call into VisIQ authenticates with an API key sent as a bearer token.
There are exactly two kinds of key, and picking the right one is the first
decision. This page is the map; each section links to the deep reference.
```bash theme={null}
Authorization: Bearer vq_prod_...
```
***
## The two key audiences
VisIQ issues keys in two **audiences**. The audience is fixed when the key is
created and determines what the key can reach.
| | Harness keys | Management keys |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Who uses it** | The SDK / harness / agents at runtime | Your scripts, CI, and back-office tooling |
| **What it reaches** | The SDK operational endpoints only — evaluation, rule bundles, HITL decision polling, telemetry, record ingestion, agent registration, discovery reporting | The management API — rules, agents, audit log, settings, and more |
| **How it's scoped** | Not scoped: full power within its route allowlist, denied everywhere else | An explicit `resource:action` permission list you choose at creation |
| **Where to create one** | **Settings → Harness Keys** (or minted for you by the SDK install studios and agent registration) | **Settings → API Keys**, or the agent device flow |
The two audiences are asymmetric. A harness key that calls a management endpoint
is rejected with `403 harness_key_not_permitted`, no matter what else it can do.
A management key is a **superset** — it may also reach the runtime endpoints its
permissions cover.
**The `vq_prod_` / `vq_test_` prefix encodes the *environment*, not the
audience.** Whether a key is a harness or a management key is fixed at creation
and shown in the dashboard — it is **not** derivable from the key string. A
`vq_prod_…` key can be either audience; read the audience from the dashboard key
table, not from the prefix.
**`test` keys are a labeling convention, not an isolated sandbox.** A `vq_test_`
key authenticates against the same tenant and the same data at
`https://api.visiqlabs.com` as a `vq_prod_` key — the prefix only helps you tell
credentials apart in logs and secret stores. There is no separate test tenant or
sandboxed dataset behind it.
If you are integrating the `@visiq/harness` SDK, you want a **harness key** — see
the [Quickstart](/quickstart). Everything below the audiences is about management
keys and the flows shared by both.
***
## Permissions & scopes
A management 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`). Enforcement is
exact and fail-closed: a request is allowed only when the route's required
permission is in the key's list, with no wildcard expansion and no implication
between permissions. Anything else returns `403 insufficient_permission`, naming
both the required permission and what the key holds.
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, so a narrowly-permissioned caller can never bootstrap a stronger key.
**Legacy scoped keys** created before explicit permissions shipped carry coarse
**scopes** instead of a permission list (for example `rules:read` / `rules:write`
/ `rules:evaluate`, or `full_access`). They are still honored, and a scope denial
returns `403 insufficient_scope`. New keys always use explicit permissions. Full
model: [The permission model](/automation/introduction#the-permission-model).
***
## Lifecycle: create, rotate, revoke
The complete lifecycle — creation dialog, key format, expiry, rotation with grace
windows, rate limits, and the error reference — lives in
[Managing API keys](/automation/api-keys). The essentials:
Name it, pick environment and expiry, select permissions. The plaintext key
is shown **exactly once** — VisIQ stores only a SHA-256 hash.
Issue a new secret for the same logical key with a configurable grace window
so in-flight callers cut over with zero downtime.
Immediate and irreversible — the next request with that key gets `401`. Every
create, rotate, and revoke is written to your audit log.
A key can always revoke **itself** — no permission required, authenticated by
the presenting key. The clean way for an agent to end its own session.
Self-revocation is authenticated by the presenting key itself, so the only key it
can ever target is the caller's own — cross-key revocation is impossible through
that path ([RFC 7009](https://www.rfc-editor.org/rfc/rfc7009) spirit):
```bash theme={null}
# Works for a harness OR a management key — make it the last call with that key
curl -X POST https://api.visiqlabs.com/allow/self/revoke \
-H "Authorization: Bearer vq_prod_..."
```
***
## Agents that mint their own key: the device flow
An AI agent can obtain its own credential without a human pasting one in, through
the human-approved `agent_auth` **device flow**
([RFC 8628](https://www.rfc-editor.org/rfc/rfc8628)-shaped). The agent registers,
shows an operator a short `user_code`, the operator reviews the requested audience
and permissions and approves, and the agent polls for the key — issued **exactly
once**. Issuance always requires a human; there is no anonymous or instant
credential, and the grant can never exceed the approver's own permissions.
By default the flow requests a **harness** key; pass
`"requested_key_type": "management"` with an explicit `requested_permissions` list
to request the management surface. See
[Agent self-registration](/automation/agent-device-flow) for the full ceremony,
and the machine-readable [agent authentication guide](https://visiqlabs.com/auth.md)
served at `visiqlabs.com/auth.md`.
***
## Operating over MCP
Once an agent holds a **management** key it can operate VisIQ through the
authenticated [Platform MCP server](/automation/mcp) — the same management
surface as the web app, with every tool gated by the identical RBAC permission
its web route requires. Point any MCP client at
`https://app.visiqlabs.com/api/mcp` with an `Authorization: Bearer` header, then
call `whoami` first to confirm the permissions your key resolves to. A harness
key is **not** accepted there; the server is fail-closed.
***
## Where each audience is documented
The runtime credential the `@visiq/harness` SDK uses. Minted by the install
studios or under **Settings → Harness Keys**.
Automation keys for scripts and CI, their permission model, and guardrails.
Full lifecycle: creation, format, expiry, rotation, rate limits, errors.
The one-line definitions of harness vs management keys.