Skip to content

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"

Verify it works

A 200 response with your quotas means authentication is working:

200 OK
{
  "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.

CheckExpected
HTTP status200
successtrue
quotas.workspace.credits.leftYour 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
  }
}
IssueFix
Missing Bearer prefixUse Authorization: Bearer rc_..., not just rc_...
Malformed credential headerUse Authorization: Bearer <api_key> or x-api-key: <api_key>
Typo or truncated keyCopy the full key again from API Keys
Revoked or deleted keyCreate a new key in the dashboard
Expired key (API_KEY_EXPIRED)Create a new key in the dashboard
Wrong workspaceCheck 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"
  • 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 the Reverse Contact API return 401 Unauthorized?

A 401 means the API key was missing (API_KEY_MISSING), not recognized (API_KEY_INVALID), sent in a malformed header (API_KEY_MALFORMED) or past its expiration date (API_KEY_EXPIRED). Check that the header reads Authorization: Bearer rc_..., that the key was copied in full and has not been revoked or deleted, and that the key belongs to the right workspace.

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