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

1. Visit the Developer Console
2. Click "Create API Key"
3. Give your key a name (e.g., "Production", "Development")
4. 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"

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

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:

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

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

Last updated on