Skip to main content
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.

​
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. 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. 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.

​
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. The essentials:

Create

Name it, pick environment and expiry, select permissions. The plaintext key is shown exactly once — VisIQ stores only a SHA-256 hash.

Rotate

Issue a new secret for the same logical key with a configurable grace window so in-flight callers cut over with zero downtime.

Revoke

Immediate and irreversible — the next request with that key gets 401. Every create, rotate, and revoke is written to your audit log.

Self-revoke

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 spirit):

​
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-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 for the full ceremony, and the machine-readable agent authentication guide 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 — 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

Harness keys (SDK)

The runtime credential the @visiq/harness SDK uses. Minted by the install studios or under Settings → Harness Keys.

Management keys

Automation keys for scripts and CI, their permission model, and guardrails.

Managing API keys

Full lifecycle: creation, format, expiry, rotation, rate limits, errors.

Glossary: key audiences

The one-line definitions of harness vs management keys.