Skip to main content
Instead of a human minting a key up front and pasting it into your agent, the agent can register itself and have a human approve it. VisIQ implements this as an RFC 8628-shaped device authorization flow (the agent_auth grant). Issuance still always requires a human to approve — there is no anonymous or instant credential.
This is the machine-readable counterpart to the agent authentication guide served for agents at visiqlabs.com/auth.md. The flow is advertised in the agent_auth block of /.well-known/oauth-authorization-server.

​
When to use it

  • Your agent runs somewhere an operator cannot pre-provision a key, but a human can approve a one-time request.
  • You want the credential bound to the approving human’s account and scoped to exactly what they agree to — never broader than their own permissions.
If an operator can simply create a key in the dashboard, use Managing API keys instead — this flow exists for the agent-initiated case.

​
The flow at a glance

  1. Agent → VisIQ: POST /api/agent/identity to register.
  2. VisIQ → Agent: returns a claim_token, a short user_code, and a verification URL.
  3. Agent → Human: show the operator the user_code / verification_uri_complete.
  4. Human → VisIQ: the operator signs in, opens the URL, reviews the requested audience and permissions, and approves.
  5. Agent → VisIQ (poll): POST /api/agent/identity/claim every interval seconds — 400 authorization_pending until approved.
  6. VisIQ → Agent: once approved, the api_key is returned exactly once.

​
Step 1 — Register

POST https://app.visiqlabs.com/api/agent/identity
By default this requests a harness key (least privilege — see key audiences). To request the full product surface, ask for a management key, optionally with an explicit permission list:
Omitting requested_permissions requests the default product grant (rules, agents, audit/outcomes, action schemas, HITL responses, settings) — but never account administration: a device-flow key cannot manage API keys, the team, or billing. The response is a device-flow ceremony:
Keep the claim_token private — it is what you exchange for the key in Step 3. Show the human the user_code / verification_uri.

​
Step 2 — Have a human approve

Show your operator the verification_uri_complete — a single clickable link with the code already embedded (RFC 8628 one-click); the code survives the sign-in / MFA detour and the approval page auto-loads your pending registration. Fall back to the bare verification_uri plus the typed user_code if a one-click link is not usable. They sign in to VisIQ, open the URL, review the requested audience and permissions, and approve. Approval mints a governed key bound to their account — harness by default, management if you requested it and they agreed. They can narrow the grant, and can never grant beyond their own permissions.

​
Step 3 — Poll for the credential

POST https://app.visiqlabs.com/api/agent/identity/claim, every interval seconds, with your claim_token:
While the human has not approved yet, you get:
(HTTP 400). Keep polling at interval seconds — do not poll faster. Once approved, you receive the credential exactly once:
  • key_type tells you which audience was actually granted (harness or management).
  • For a management key, permissions is the exact grant list your credential holds; it is null for a harness key.
The api_key is shown once. Store it in your secret manager immediately — VisIQ keeps only a SHA-256 hash and cannot show it again. If you lose it, revoke it and register again.
Claim tickets expire after 30 minutes. If the ceremony lapses (the human never approves in time), register again for a fresh user_code. Then use the key as a Bearer token — see Use a key.

​
Revoking

You can retire a device-flow credential yourself, at any time:
  • Cancel or revoke the device-flow credential — POST https://app.visiqlabs.com/api/agent/identity/revoke with { "token": "vq_prod_..." } (an issued key) or { "claim_token": "vqac_..." } (the pending ticket, which also revokes an already-issued key).
  • Self-revoke any key you hold — POST /allow/self/revoke, authenticated by the key itself, no permission required. See Revoke your own key.

​
Prefer MCP?

Once you hold a management key you can operate VisIQ through the Platform MCP server instead of raw REST — including retiring the key with the revoke_self tool when you are done.