Introduction

Authentication

Updated

Authenticate requests to the Reverse Contact API.

Every API request requires your key in the Authorization header. Two steps and you're set.

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:

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.

Check	Expected
HTTP status	`200`
`success`	`true`
`quotas.workspace.credits.left`	Your remaining credits

Ready to enrich your first profile? Continue with Your first API call.

Something went wrong?

A 401 response means the API key was missing, malformed, or not recognized:

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
Wrong workspace	Check you're using a key from the right workspace

A valid key for a suspended workspace returns 403 WORKSPACE_DISABLED, because the request is authenticated but the workspace is not authorized to use the API.

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 keys. Revoke compromised keys and generate new ones from API Keys.
Never expose keys in client-side code, public repos, or browser JavaScript.
Monitor usage with GET /v2/usage to track credits and rate limits.