Authentication

The Verity API uses API keys for authentication. All requests must include a valid API key in the Authorization header.

Getting an API Key

Visit the Developer Console
Click "Create API Key"
Give your key a name (e.g., "Production", "Development")
Copy and securely store the key - it won't be shown again

Using Your API Key

Include your API key in the Authorization header using the Bearer scheme:

curl -X GET "https://verity.backworkai.com/api/v1/health" \
  -H "Authorization: Bearer vrt_live_xxxx"

Keep Your Key Secret

Never expose your API key in client-side code, public repositories, or logs. If you suspect your key has been compromised, revoke it immediately and create a new one.

Key Format

API keys follow this format:

vrt_{mode}_{random}_checksum

vrt - Prefix identifying Verity API keys
mode - Either live (production) or test (development)
random - Cryptographically random string
checksum - 4-character checksum for validation

Test vs Live Keys

Key Type	Prefix	Use Case
Live	`vrt_live_`	Production applications
Test	`vrt_test_`	Development and testing

Both key types have access to the same endpoints and data. Test keys are useful for development to avoid affecting production usage metrics.

API Key Scopes

Most API keys can read policy, code, coverage, and prior-auth endpoints with the default read scope.

Mutating endpoints require an API key with write or admin scope:

Endpoint	Required Scope
`POST /v1/webhooks`	`write` or `admin`
`PATCH /v1/webhooks/{id}`	`write` or `admin`
`DELETE /v1/webhooks/{id}`	`write` or `admin`
`POST /v1/webhooks/{id}/test`	`write` or `admin`
`POST /v1/compliance/ack`	`write` or `admin`
`POST /v1/compliance/ack/bulk`	`write` or `admin`

Use the narrowest scope needed for each integration. The admin scope satisfies all read and write checks.

MCP Authentication

Direct Verity API integrations should use API keys. For hosted MCP clients that support OAuth, such as Claude Code, use the hosted MCP setup instead of copying an API key into the client.

The hosted MCP OAuth flow signs the user into Verity, asks for consent, and issues an access token scoped to the MCP resource. MCP requests still count as Verity API usage and are attributed to the signed-in user, OAuth client, organization, and MCP tool when available.

See the MCP Server guide for Claude Code setup, local API-key setup, and self-hosted OAuth configuration.

Code Examples

import requests
import os

response = requests.get(
    'https://verity.backworkai.com/api/v1/health',
    headers={'Authorization': f'Bearer {os.environ["VERITY_API_KEY"]}'}
)

const response = await fetch('https://verity.backworkai.com/api/v1/health', {
  headers: {
    'Authorization': `Bearer ${process.env.VERITY_API_KEY}`
  }
});

curl -X GET "https://verity.backworkai.com/api/v1/health" \
  -H "Authorization: Bearer $VERITY_API_KEY"

Error Responses

If authentication fails, you'll receive a 401 Unauthorized response:

{
  "success": false,
  "error": {
    "code": "AUTH_INVALID_KEY",
    "message": "Invalid API key",
    "hint": "Check that your API key is correct and active"
  }
}

Common Authentication Errors

Error Code	Description
`AUTH_MISSING`	No Authorization header provided
`AUTH_INVALID_FORMAT`	Authorization header format is wrong
`AUTH_INVALID_KEY`	API key is invalid or not found
`AUTH_REVOKED_KEY`	API key has been revoked
`AUTH_SUSPENDED_KEY`	API key is suspended

Last updated on

Authentication

On this page