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 below. The default grant never includes account administration: a key minted from the default grant cannot manage API keys, the team, or billing.
  • dashboard:view
  • allow_rules:view
  • allow_rules:create
  • allow_rules:update
  • allow_rules:delete
  • recall_rules:view
  • recall_rules:create
  • recall_rules:update
  • recall_rules:delete
  • allow_agents:view
  • allow_agents:create
  • allow_agents:update
  • allow_agents:delete
  • allow_audit_log:view
  • recall_audit_log:view
  • record_records:view
  • record_audit_log:view
  • audit_log:view
  • events:view
  • allow_hitl:view
  • allow_hitl:respond
  • allow_settings:view
  • allow_settings:update
An explicit requested_permissions list may name any permission in the catalogue, account administration included. The approver sees the full list before approving, and the grant is always bounded by what the approver holds: nobody can approve a permission they do not have themselves. Registration is rate-limited per client IP (10 per minute and 100 per hour, counted across every VisIQ server). Over the limit you get 429 {"error": "rate_limited"} with a Retry-After header; if the limiter itself cannot answer, you get 503 {"error": "temporarily_unavailable"} and should retry later. 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 is for signed-in people only: a request to the approval endpoint made with an API key (management keys included) is refused with 403, so one agent can never approve another. 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. If you poll sooner than that, you get slow_down instead (RFC 8628 section 3.5), also HTTP 400, carrying the new, longer interval to use from then on:
Each slow_down adds 5 seconds, up to 60. Once approved, you receive the credential exactly once, whatever your polling pace:
  • 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). An unknown or already-revoked token still gets 200, so the endpoint never reveals whether a token existed. If the revoke could not be completed you get 503 {"error": "temporarily_unavailable"}: treat the key as still live and retry. Revoking a live key is recorded in the approving account’s audit log as AGENT_KEY_REVOKED (a denied registration is recorded as AGENT_REGISTRATION_DENIED, an issued key as AGENT_KEY_ISSUED).
  • 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.