Skip to main content

​
Overview

Vouch uses API keys for authentication. Every request must include:
  1. Authorization header with your API key
  2. X-Project-Id header with your project ID
Authorization: Bearer your_api_key
X-Project-Id: your_project_id

​
API Key Types

Vouch provides two types of API keys, each with different use cases and security characteristics:

Client Keys

For browser and mobile apps
  • Restricted to allowed domains
  • 1,000 requests/hour
  • Safe to expose in client code
  • Automatic device fingerprinting
  • Cannot override IP/User-Agent

Server Keys

For backend services
  • No domain restrictions
  • 5,000 requests/hour
  • Must be kept secret
  • Can override IP/User-Agent
  • Blocked from browsers

​
Test vs Live Environments

Each project gets 4 API keys:
EnvironmentKey TypePurpose
TestClientDevelopment in browsers
TestServerDevelopment on servers
LiveClientProduction in browsers
LiveServerProduction on servers
Test keys don’t count against your monthly quota. Use them during development.

​
Security Features

​
Server Key Browser Protection

Server keys are automatically blocked when used from browsers to prevent accidental exposure. Detection happens via:
  • Origin header presence
  • Referer header presence
  • User-Agent indicating browser
// Response when server key used in browser
{
  "success": false,
  "error": {
    "code": "INVALID_KEY_TYPE",
    "message": "Server keys cannot be used in browsers"
  }
}
If you try to use a server key in client-side code, you’ll immediately get a 401 error.

​
Client Key Domain Validation

Client keys are validated against your allowed domains list. Configure allowed domains in your dashboard: Allowed Domain Patterns:
  • example.com - Exact match
  • *.example.com - Wildcard subdomain
  • localhost:3000 - Development domains
// Response when domain not allowed
{
  "success": false,
  "error": {
    "code": "DOMAIN_NOT_ALLOWED",
    "message": "Origin not in allowed domains list"
  }
}

​
Authentication Examples

  • JavaScript (Client)
  • Node.js (Server)
  • cURL
  • Python
const vouch = new Vouch(
  'your-project-id',
  'your-client-key' // CLIENT key for browser
);

const result = await vouch.validate('[email protected]');

​
Managing API Keys

​
Finding Your Keys

  1. Go to vouch.expert/dashboard
  2. Select your project
  3. Navigate to Settings → API Keys
  4. Copy the appropriate key for your environment

​
Regenerating Keys

If a key is compromised:
  1. Navigate to API Keys in your project settings
  2. Click Regenerate next to the compromised key
  3. Update your application with the new key
  4. Old key is immediately invalidated
Regenerating a key immediately invalidates the old key. Update your application before regenerating production keys.

​
Best Practices

Use environment variables instead:
# .env (never commit this file)
VOUCH_PROJECT_ID=your_project_id
VOUCH_CLIENT_KEY=your_client_key
VOUCH_SERVER_KEY=your_server_key

// Good
const vouch = new Vouch(
  process.env.VOUCH_PROJECT_ID,
  process.env.VOUCH_SERVER_KEY
);

// Bad
const vouch = new Vouch(
  'proj_1234567890',
  'sk_live_1234567890abcdef'
);
Test keys don’t count against quota:
const apiKey = process.env.NODE_ENV === 'production'
  ? process.env.VOUCH_LIVE_KEY
  : process.env.VOUCH_TEST_KEY;

const vouch = new Vouch(projectId, apiKey);
For security, rotate API keys every 90 days:
  1. Generate new key
  2. Deploy with new key
  3. Verify everything works
  4. Delete old key
Never use server keys in client-side code:
// Good - Client key in browser
const vouch = new Vouch(projectId, clientKey);

// Bad - Server key in browser (will be blocked)
const vouch = new Vouch(projectId, serverKey);
Configure allowed domains to prevent unauthorized use:
  • Add localhost:* for development
  • Add your production domains
  • Use wildcards carefully (*.example.com)

​
Error Responses

​
Invalid API Key

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key",
    "status": 401
  }
}

​
Missing Project ID

{
  "success": false,
  "error": {
    "code": "MISSING_PROJECT_ID",
    "message": "X-Project-Id header is required",
    "status": 400
  }
}

​
Wrong Key Type

{
  "success": false,
  "error": {
    "code": "INVALID_KEY_TYPE",
    "message": "Server keys cannot be used in browsers",
    "status": 401
  }
}

​
Domain Not Allowed

{
  "success": false,
  "error": {
    "code": "DOMAIN_NOT_ALLOWED",
    "message": "Origin 'https://unauthorized.com' not in allowed domains",
    "status": 403
  }
}

​
Next Steps

Client vs Server Keys

Deep dive into key type differences

API Reference

Explore the validation endpoint

Error Handling

Handle authentication errors

Dashboard

Manage your API keys