Authentication & Security | API Documentation

Overview

All VeriRoute Intel APIs use API key authentication for secure access. This guide covers how to obtain, configure, and use your API keys across our specialized services:

CNAM API: Caller ID name lookup
Message Provider API: SMS carrier identification
LRN API: Local routing number lookup
Brand Reputation API: Spam and robocall detection
Traceback Search API: Call trace and investigation

How to Obtain an API Key

Getting started with VeriRoute Intel's API is simple and secure. Follow these steps to obtain your API key:

Create an Account: Sign up for a free account on our platform
Verify Your Email: Check your inbox and click the verification link
Access Dashboard: Log in and navigate to your API Keys section
Generate API Key: Click "Generate New API Key" and provide a descriptive name
Secure Storage: Copy and store your API key securely (it won't be shown again)
Start Testing: Use your API key immediately with our endpoints

💡 Pro Tip

You can generate multiple API keys for different applications or environments (development, staging, production).

API Key Authentication

All API requests must include your API key in the request header. VeriRoute Intel uses a simple and secure header-based authentication system.

Header Format

Include your API key in the Authorization header with Bearer token format:

Authorization: Bearer your_api_key_here

Example Request

curl -X POST "https://api-service.verirouteintel.io/api/v1/cnam" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "15555550123"}'

🔒 Authentication Response

If authentication fails, you'll receive a 401 Unauthorized response with details about the authentication error.

Security Best Practices

Follow these essential security practices to protect your API keys and ensure secure communication:

API Key Security

Never expose API keys in client-side code: Keep keys on your server-side applications only
Use environment variables: Store API keys in environment variables, not in your source code
Rotate keys regularly: Generate new API keys periodically and deactivate old ones
Use different keys per environment: Separate keys for development, staging, and production
Monitor key usage: Regularly review API key activity in your dashboard
Implement key restrictions: Use IP whitelisting when possible to limit key usage

Network Security

Always use HTTPS: All API requests must use SSL/TLS encryption
Validate SSL certificates: Ensure your HTTP client validates our SSL certificates
Implement request timeouts: Set appropriate timeouts to prevent hanging connections
Use secure HTTP methods: Follow RESTful principles for GET, POST, PUT, DELETE operations

Data Protection

Sanitize input data: Validate and sanitize all phone numbers before sending
Handle responses securely: Don't log sensitive data from API responses
Implement rate limiting: Respect our rate limits and implement client-side throttling
Cache responsibly: Cache responses appropriately but respect data freshness requirements

⚠️ Security Alert

If you suspect your API key has been compromised, immediately generate a new key and deactivate the old one through your dashboard.

Authentication Error Handling

Understanding and properly handling authentication errors is crucial for a robust integration:

Common Authentication Errors

401 Unauthorized

Cause: Missing or invalid API key

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or missing",
    "details": "Please check your X-API-Key header"
  }
}

403 Forbidden

Cause: API key lacks required permissions or account suspended

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Your API key does not have permission for this operation",
    "details": "Contact support to upgrade your plan"
  }
}

429 Too Many Requests

Cause: Rate limit exceeded

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": "Try again in 60 seconds",
    "retry_after": 60
  }
}

API Key Management

Effective API key management ensures security and operational efficiency:

Key Lifecycle

Generation: Create keys with descriptive names and appropriate permissions
Distribution: Securely share keys with authorized team members only
Monitoring: Track usage patterns and identify anomalies
Rotation: Replace keys regularly or when team members leave
Revocation: Immediately deactivate compromised or unused keys

Dashboard Features

Your API Keys dashboard provides:

Real-time usage statistics and request counts
Last used timestamps for each API key
Ability to generate, rename, and delete keys
Usage alerts and notifications
Integration logs and error tracking

API Authentication