Authentication

All API requests require authentication using an API key. This page covers key formats, sandbox mode, and security best practices.

API Key Format

VertaaUX uses prefixed API keys that indicate the key type:

Example keys:

vx_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
vx_test_x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4

Using Your API Key

Include your API key in the X-API-Key header with every request:

const response = await fetch('https://vertaaux.ai/api/v1/audit', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.VERTAAUX_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url: 'https://example.com' }),
});

curl -X POST https://vertaaux.ai/api/v1/audit \
  -H "X-API-Key: vx_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

import os
import requests

response = requests.post(
    'https://vertaaux.ai/api/v1/audit',
    headers={
        'X-API-Key': os.environ['VERTAAUX_API_KEY'],
        'Content-Type': 'application/json',
    },
    json={'url': 'https://example.com'}
)

Sandbox Mode

Use sandbox mode for development and testing without consuming your quota.

Enabling Sandbox Mode

Option 1: Use a test key (recommended)

Keys prefixed with vx_test_ automatically enable sandbox mode:

X-API-Key: vx_test_your_test_key

Option 2: Use the sandbox header

Add the x-vertaaux-sandbox header with any key:

X-API-Key: vx_live_your_key
x-vertaaux-sandbox: true

Sandbox Behavior

Getting an API Key

Key Management

Rotation

Rotate your API keys regularly to minimize risk from potential exposure:

• Production keys: Rotate every 90 days
• After potential exposure: Rotate immediately
• Team member departure: Rotate shared keys

To rotate a key:

1. Create a new key with the same permissions
2. Update your applications to use the new key
3. Verify the new key works
4. Revoke the old key

Scoping

Create separate keys for different purposes:

Revocation

Revoke compromised or unused keys immediately:

1. Go to Dashboard > Settings > API Keys
2. Find the key to revoke
3. Click Revoke
4. Confirm the action

Security Best Practices

Environment Variables

Never hardcode API keys. Use environment variables:

# .env (add to .gitignore!)
VERTAAUX_API_KEY=vx_live_your_key

// Access in code
const apiKey = process.env.VERTAAUX_API_KEY;

Never Commit Keys

Add sensitive files to .gitignore:

# .gitignore
.env
.env.local
.env.*.local
*.pem

Server-Side Only

Never expose API keys in client-side code:

// BAD - Key exposed to browser
const apiKey = 'vx_live_secret'; // Visible in browser DevTools!

// GOOD - Call your own backend
const response = await fetch('/api/run-audit', {
  method: 'POST',
  body: JSON.stringify({ url }),
});

CI/CD Secrets

Use your CI provider's secret management:

GitHub Actions:

- name: Run audit
  env:
    VERTAAUX_API_KEY: ${{ secrets.VERTAAUX_API_KEY }}
  run: npx vertaa audit --url ${{ github.event.deployment.payload.url }}

GitLab CI:

audit:
  script:
    - npx vertaa audit --url $DEPLOY_URL
  variables:
    VERTAAUX_API_KEY: $VERTAAUX_API_KEY  # From CI/CD settings

Troubleshooting

401 Unauthorized

"Invalid or missing API key"

1. Verify the key is copied correctly (no extra spaces)
2. Check you are using the correct header: X-API-Key (not Authorization: Bearer)
3. Confirm the key has not been revoked

401 API Key Revoked

"API key has been revoked"

The key was explicitly revoked. Create a new key in your Dashboard.

401 API Key Expired

"API key has expired"

Some keys have expiration dates. Create a new key or extend the expiration in your Dashboard.

403 Forbidden

"You don't have permission to access this resource"

The API key does not have permission for this operation. This can happen when:

• Accessing another user's audit results
• Using a read-only key for write operations

Related