Authentication

All API requests must include a valid API key in the Authorization header. ScamVerify™ uses Bearer token authentication.

Bearer Token Format

Include your API key in the Authorization header of every request:

Authorization: Bearer sv_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789ab

API keys are 48 characters long: an 8-character prefix (sv_live_ or sv_test_) followed by 40 base64url characters.

Test Keys vs Live Keys

ScamVerify™ provides two types of API keys for different stages of development.

Key Management

Manage your API keys from the API dashboard.

Creating a Key

1. Navigate to Settings > API in your dashboard
2. Click Create API Key
3. Enter a descriptive name (e.g., "production-backend" or "staging-server")
4. Choose whether to create a test key or live key
5. Copy the key immediately and store it in a secure location

Revoking a Key

If a key is compromised or no longer needed, revoke it from the dashboard. Revoked keys stop working immediately. Any requests using a revoked key will receive a 401 Unauthorized response.

Renaming a Key

You can rename a key at any time from the dashboard. Renaming does not change the key value or affect its functionality. Use descriptive names to keep track of which key is used where.

Key Limits

Each account can have up to 5 active API keys. If you need more, revoke unused keys to free up slots.

Code Examples

curl -X POST https://scamverify.ai/api/v1/phone/lookup \
  -H "Authorization: Bearer $SCAMVERIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+12025551234"}'

import os
import requests

api_key = os.environ["SCAMVERIFY_API_KEY"]

response = requests.post(
    "https://scamverify.ai/api/v1/phone/lookup",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={"phone_number": "+12025551234"},
)

print(response.json())

const apiKey = process.env.SCAMVERIFY_API_KEY;

const response = await fetch("https://scamverify.ai/api/v1/phone/lookup", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+12025551234" }),
});

const data = await response.json();
console.log(data);

Error Responses

When authentication fails, the API returns one of these error responses:

Missing API Key

If the Authorization header is not provided:

{
  "error": "missing_api_key",
  "message": "The Authorization header is required. Include your API key as a Bearer token.",
  "status": 401
}

Invalid API Key

If the key is malformed, revoked, or does not exist:

{
  "error": "invalid_api_key",
  "message": "The provided API key is invalid or has been revoked.",
  "status": 401
}

Expired Subscription

If the account associated with the key has no active subscription:

{
  "error": "subscription_required",
  "message": "An active subscription is required to use this API. Visit https://scamverify.ai/settings/api to manage your plan.",
  "status": 403
}

Security Best Practices

• Use environment variables. Never hardcode API keys in your source code. Store them in environment variables or a secrets manager.
• Never commit keys to version control. Add your .env file to .gitignore and use .env.example files with placeholder values.
• Rotate keys if compromised. If you suspect a key has been exposed, revoke it immediately from the dashboard and create a new one.
• Use separate keys per environment. Create distinct keys for development, staging, and production. This makes it easy to revoke a single key without affecting other environments.
• Use test keys for development. Avoid consuming your quota during development by using sv_test_ keys.
• Restrict key access. Only share API keys with team members and systems that need them. Follow the principle of least privilege.