Authentication

The UserCheck API authenticates with an API key, passed in the Authorization header as a bearer token.

The lookup endpoints answer unauthenticated requests too, but at 5 requests per hour and without the fields your plan adds, so every real integration should send a key. The /status, blocklist, and Gates endpoints reject requests that carry no valid key with 401. On the Gates endpoints, that becomes 429 after 5 such requests in an hour from one IP; see Rate Limits.

Getting your API key

1. Sign up for an account at app.usercheck.com
2. Log in to your dashboard
3. Go to the API Keys section
4. Generate a new key, or copy an existing one

Each key belongs to one environment, and the key you send is what decides which environment a request runs against. There is no environment parameter.

On a plan that includes Gates, every key can also use the Gates Management API, even a key you only use for lookups. Anyone holding it can change or delete the gates in its environment and read their decision logs, which include the emails and IPs you sent. Keep keys secret, and revoke any key you have shared.

Using your API key

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

curl -X GET "https://api.usercheck.com/email/[email protected]" \
  -H "Authorization: Bearer YOUR_API_KEY"

Alternative: query parameter (not recommended)

The key can also be passed as a key query parameter, on every endpoint except the Gates ones, which accept the header only. This is not recommended: query strings are written to server access logs, kept in browser history, and can leak through referrer headers, none of which happens with a header.

curl -X GET "https://api.usercheck.com/email/[email protected]?key=YOUR_API_KEY"

Authentication examples

JavaScript (fetch)

const response = await fetch('https://api.usercheck.com/email/[email protected]', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

Python (requests)

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('https://api.usercheck.com/email/[email protected]', headers=headers)

PHP

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.usercheck.com/email/[email protected]');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

Verify your setup

Once you've configured your API key, you can call the GET /status endpoint to confirm everything is working correctly:

curl -X GET "https://api.usercheck.com/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

A 200 response means the key is valid and reports the plan and remaining credits it is attached to. A 401 means the key was missing or is not recognized. See the Status endpoint for the full response format.