Authentication

Overview

Vouch uses API keys for authentication. Every request must include:

Authorization header with your API key
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

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
{
  "error": "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
app://com.yourapp.example - Mobile apps (iOS/Android)

Mobile App Domains

The Vouch iOS and Android SDKs automatically send an Origin header using your app’s bundle identifier / package name in the format app://your.bundle.id. You need to add this as an allowed domain in your dashboard.

iOS
Android

The SDK uses your app’s Bundle Identifier (e.g., com.example.myapp):

// The SDK automatically sets this header:
// Origin: app://com.example.myapp

Add app://com.example.myapp to your allowed domains.

The SDK uses your app’s applicationId / package name (e.g., com.example.myapp):

// The SDK automatically sets this header:
// Origin: app://com.example.myapp

Add app://com.example.myapp to your allowed domains.

You can find your bundle identifier in Xcode (iOS) or your build.gradle file (Android).

// Response when domain not allowed
{
  "error": "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]');

const vouch = new Vouch(
  process.env.VOUCH_PROJECT_ID,
  process.env.VOUCH_SERVER_KEY // SERVER key for backend
);

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

curl -X POST https://api.vouch.expert/validate \
  -H "Authorization: Bearer your_server_key" \
  -H "X-Project-Id: your_project_id" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

import os
import requests

headers = {
    'Authorization': f'Bearer {os.getenv("VOUCH_SERVER_KEY")}',
    'X-Project-Id': os.getenv('VOUCH_PROJECT_ID'),
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://api.vouch.expert/validate',
    headers=headers,
    json={'email': '[email protected]'}
)

Managing API Keys

Finding Your Keys

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

Regenerating Keys

If a key is compromised:

Navigate to API Keys in your project settings
Click Regenerate next to the compromised key
Update your application with the new key
Old key is immediately invalidated

Regenerating a key immediately invalidates the old key. Update your application before regenerating production keys.

Best Practices

Never commit API keys to version control

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'
);

Rotate keys periodically

For security, rotate API keys every 90 days:

Generate new key
Deploy with new key
Verify everything works
Delete old key

Use client keys in browsers

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);

Restrict client key domains

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

{
  "error": "Invalid API key"
}

HTTP Status: 401

Missing Project ID

{
  "error": "X-Project-Id header is required"
}

HTTP Status: 400

Wrong Key Type

{
  "error": "Server keys cannot be used in browsers"
}

HTTP Status: 401

Domain Not Allowed

{
  "error": "Origin 'https://unauthorized.com' not in allowed domains"
}

HTTP 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

​Overview

​API Key Types

Client Keys

Server Keys

​Security Features

​Server Key Browser Protection

​Client Key Domain Validation

​Mobile App Domains

​Authentication Examples

​Managing API Keys

​Finding Your Keys

​Regenerating Keys

​Best Practices

​Error Responses

​Invalid API Key

​Missing Project ID

​Wrong Key Type

​Domain Not Allowed

​Next Steps

Client vs Server Keys

API Reference

Error Handling

Dashboard

Overview

API Key Types

Security Features

Server Key Browser Protection

Client Key Domain Validation

Mobile App Domains

Authentication Examples

Managing API Keys

Finding Your Keys

Regenerating Keys

Best Practices

Error Responses

Invalid API Key

Missing Project ID

Wrong Key Type

Domain Not Allowed

Next Steps