API keys

Project API keys authenticate your CI/CD pipelines with VisualQ. Each key is scoped to a single project.

For Cursor, Claude Desktop, and QA agents that work across multiple projects, use org agent API keys (vq_org_live_…) instead — created under Settings → Agent API Keys.

Creating an API key

Go to Settings

Navigate to your project's Settings tab.

Find the API Keys section

Scroll to the API Keys section.

Create a new key

Click "Create API key". A new key will be generated and displayed.

Copy the key immediately

The full key is only shown once. Copy it and store it securely (e.g., in your CI system's secrets).

Choose a scope (optional)

Select CI only, MCP read, or MCP full depending on how the key will be used. Defaults to MCP full (read + write + CI).

API keys are shown only once at creation. If you lose a key, revoke it and create a new one.

Using API keys

Include the API key in the X-API-Key header when calling the REST API:

curl -X POST https://visualq.ai/api/ci/run \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{"project": "my-project"}'

Or pass it to the GitHub Action:

- uses: abecms/visualq-action@v1
  with:
    api-key: ${{ secrets.VISUALQ_API_KEY }}
    project: my-project

API key scopes

Each key can be restricted to a specific use case:

Scope	CI runs	MCP read	MCP write
`ci`	yes	no	no
`mcp_read`	no	yes	no
`mcp_full`	yes	yes	yes

CI pipelines — use ci or mcp_full
IDE agents (read-only) — use mcp_read or mcp_full on a project key, or an org agent key
IDE agents that approve baselines or post PR comments — use mcp_full (project or org agent key)

Keys created before scopes were introduced default to mcp_full. See MCP integration for tool and scope details.

Revoking a key

From the API Keys section in Settings, click Revoke next to any key. The key is immediately invalidated and can no longer be used for authentication.

Security best practices

Store API keys in your CI system's secrets or environment variables
Never commit API keys to your repository
Rotate keys periodically
Revoke keys that are no longer needed