Authentication
How to authenticate with the VisualQ API.
API key authentication (recommended)
For CI/CD, MCP, webhooks, and automation, use an API key in the X-API-Key header:
X-API-Key: your-api-key-hereAPI keys are scoped to an organization and optionally a single project:
| Key type | Prefix | Where to create |
|---|---|---|
| Org agent | vq_org_live_… | Settings → Agent API Keys — guide |
| Project | vq_live_… | Project → Settings → API Keys — guide |
Org agent keys power MCP clients across all projects. Project keys are for CI/CD and single-project automation.
Dashboard sign-in (browser only)
When you use VisualQ in the browser, your account session is managed automatically after sign-in. You do not need to configure anything for normal dashboard use.
A small set of test endpoints (trigger a pillar run from custom scripts while logged in) accept the same session as the dashboard. Prefer API keys for CI and long-running automation — they do not expire when your browser session ends.
If you belong to multiple organizations, the dashboard and session-backed calls use your active organization. API keys are already scoped to the correct org (and project, when applicable).
Error responses
| Status | Meaning |
|---|---|
401 Unauthorized | Missing or invalid credentials |
403 Forbidden | Credentials don't have access to the requested resource |
404 Not Found | Resource not found or not accessible with these credentials |
429 Too Many Requests | Rate limit exceeded |
All error responses follow this format:
{
"error": "Description of what went wrong"
}