Authentication

All API requests require authentication using an API key. This guide covers how to create, manage, and use API keys securely.

API Keys

API keys are the primary method of authenticating with the Check API. Each key is:

• Scoped to your organization
• Trackable for usage and billing
• Revocable at any time
• Prefixed with vfy_ for easy identification

Creating an API Key

1. Navigate to your Dashboard
2. Click Create New Key
3. Give your key a descriptive name (e.g., "Production Server", "Development", "CI/CD Pipeline")
4. Copy the key immediately - it won't be shown again

Using API Keys

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

Authorization: Bearer vfy_abc123...

Example Request

Bring Your Own Key (BYOK)

Check supports using your own LLM provider API keys for verification. This gives you:

• Cost control - Use your existing provider agreements
• Compliance - Keep API calls within your organization's accounts
• Flexibility - Switch providers without changing Check integration

Supported Providers

Adding Provider Keys

1. Go to Dashboard → Settings → Provider Keys
2. Click Add Provider Key
3. Select the provider
4. Enter your API key (encrypted at rest with AES-256-GCM)
5. Save

Provider keys are used automatically when you make verification requests.

Security Best Practices

Do

• Store API keys in environment variables
• Use different keys for development and production
• Rotate keys periodically (every 90 days recommended)
• Delete keys that are no longer needed
• Use secrets managers in production (AWS Secrets Manager, HashiCorp Vault, etc.)
• Monitor key usage in the dashboard

Don't

• Commit API keys to version control
• Expose keys in client-side code
• Share keys across teams without tracking
• Use production keys for testing
• Log API keys in application logs

Managing Keys

Viewing Usage

Each API key tracks its usage automatically. View statistics in your Dashboard:

• Total requests made
• Last used timestamp
• Active/inactive status
• Cost breakdown

Key Naming Conventions

Use descriptive names to organize your keys:

production-server
staging-server
development-local
ci-cd-pipeline
third-party-integration-name

Revoking Keys

To revoke a compromised or unused key:

1. Go to Dashboard → API Keys
2. Find the key you want to revoke
3. Click the Delete button
4. Confirm the deletion

Rate Limits by Plan

API rate limits are determined by your subscription plan:

See Rate Limiting for more details on handling rate limit errors.

Error Responses

401 Unauthorized

Returned when the API key is missing or invalid:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

403 Forbidden

Returned when the API key is valid but lacks permissions:

{
  "error": {
    "code": "forbidden",
    "message": "API key does not have permission to access this resource"
  }
}

Organization Access

API keys are scoped to your organization. All team members with appropriate roles can:

• Owner/Admin: Create, view, and delete API keys
• Member: View API keys (masked), cannot create or delete
• Viewer: Cannot access API key management

See Team Management for more on roles and permissions.