Authentication
Authenticate requests to the Reverse Contact API with a Bearer API key in the Authorization header, and fix 401 errors from a missing or expired key.
Every API request requires your key in the Authorization header. Setting it up takes two steps.
1. Copy your API key
Open Workspace > API Keys and copy your key. It starts with rc_*****.
2. Add it to your request
Test with the Usage endpoint. It returns your credit balance and costs zero credits:
curl https://api.reversecontact.com/v2/usage \
-H "Authorization: Bearer YOUR_API_KEY"const response = await fetch("https://api.reversecontact.com/v2/usage", {
headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const { quotas } = await response.json();
console.log("Credits left:", quotas.workspace.credits.left);import requests
response = requests.get(
"https://api.reversecontact.com/v2/usage",
headers={ "Authorization": "Bearer YOUR_API_KEY" }
)
data = response.json()
print("Credits left:", data["quotas"]["workspace"]["credits"]["left"])Verify it works
A 200 response with your quotas means authentication is working:
{
"success": true,
"quotas": {
"creditsConsumed": 0,
"workspace": {
"credits": { "total": 4000, "used": 31, "left": 3969 },
"minuteRateLimit": { "limit": 500, "left": 500 }
}
}
}See the full response structure for all fields.
| Check | Expected |
|---|---|
| HTTP status | 200 |
success | true |
quotas.workspace.credits.left | Your remaining credits |
Next, enrich your first profile with Your first API call.
Fix authentication errors
A 401 response means the API key was missing, malformed, not recognized, or expired (API_KEY_EXPIRED):
401 Unauthorized
{
"success": false,
"data": null,
"error": {
"code": "API_KEY_MISSING",
"message": "API Key is required"
},
"metadata": {
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"executionTimeMs": 1
}
}{
"success": false,
"data": null,
"error": {
"code": "API_KEY_INVALID",
"message": "API Key is invalid"
},
"metadata": {
"requestId": "f6e5d4c3-b2a1-0987-fedc-ba9876543210",
"executionTimeMs": 1
}
}{
"success": false,
"data": null,
"error": {
"code": "API_KEY_MALFORMED",
"message": "Malformed Authorization header. Expected 'Authorization: Bearer <api_key>' or 'x-api-key: <api_key>'."
}
}| Issue | Fix |
|---|---|
Missing Bearer prefix | Use Authorization: Bearer rc_..., not just rc_... |
| Malformed credential header | Use Authorization: Bearer <api_key> or x-api-key: <api_key> |
| Typo or truncated key | Copy the full key again from API Keys |
| Revoked or deleted key | Create a new key in the dashboard |
Expired key (API_KEY_EXPIRED) | Create a new key in the dashboard |
| Wrong workspace | Check you're using a key from the right workspace |
A valid key can still get a 403, for one of two reasons: the workspace is suspended (WORKSPACE_DISABLED), or the key lacks the permission the endpoint needs (INSUFFICIENT_PERMISSIONS, see API key management).
For all error codes and retry strategies, see Error handling & retries.
Keep your key safe
Store your key in an environment variable. Never hardcode it:
export RC_API_KEY="rc_0123456789abcdef0123456789abcdef"$env:RC_API_KEY = "rc_0123456789abcdef0123456789abcdef"RC_API_KEY=rc_0123456789abcdef0123456789abcdef- Use one key per environment (dev, staging, production).
- Rotate your keys: revoke compromised keys and generate new ones from API Keys.
- Never expose keys in client-side code, public repos, or browser JavaScript.
- Monitor credits and rate limits with
GET /v2/usage.
FAQ
How do I authenticate requests to the Reverse Contact API?
Copy your API key, which starts with rc_, from Workspace > API Keys and send it with every request as Authorization: Bearer <api_key>. The Reverse Contact API also accepts the key in an x-api-key: <api_key> header.
How can I test my API key without spending credits?
Call the Reverse Contact Usage endpoint, GET /v2/usage, which returns your credit balance and costs zero credits. A 200 response with success: true and your quotas means authentication is working. The full response is documented on the Usage endpoint page.
Why does a valid API key return 403?
A 403 means the request is authenticated but not allowed, for one of two reasons: the workspace is suspended (WORKSPACE_DISABLED), or the API key lacks the permission the endpoint needs (INSUFFICIENT_PERMISSIONS). See Error handling & retries.
Can I put my Reverse Contact API key in front-end code?
No. Never expose a Reverse Contact API key in client-side code, public repos or browser JavaScript: store the key in an environment variable such as RC_API_KEY and never hardcode it. Use one key per environment (dev, staging, production), and revoke compromised keys and generate new ones from Workspace > API Keys.
Last verified