# Authentication

> 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](https://app.reversecontact.com/api-keys)** and copy your key. It starts with `rc_*****`.

> [!TIP]
> Don't have an account yet? Start with [Getting started](https://docs.reversecontact.com/getting-started).

## 2. Add it to your request

Test with the [Usage endpoint](https://docs.reversecontact.com/endpoints/usage). It returns your credit balance and costs zero credits:

```bash [cURL]
curl https://api.reversecontact.com/v2/usage \
  -H "Authorization: Bearer YOUR_API_KEY"
```
```javascript [JavaScript]
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);
```
```python [Python]
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:

```json [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](https://docs.reversecontact.com/endpoints/usage) for all fields.

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

> [!NOTE]
> You're all set! Your API key is working.

Ready to enrich your first profile? Continue with [Your first API call](https://docs.reversecontact.com/guides/first-api-call).

## Something went wrong?

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

**401 Unauthorized**

```json [Key Missing]
{
  "success": false,
  "data": null,
  "error": {
    "code": "API_KEY_MISSING",
    "message": "API Key is required"
  },
  "metadata": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "executionTimeMs": 1
  }
}
```
```json [Key Invalid]
{
  "success": false,
  "data": null,
  "error": {
    "code": "API_KEY_INVALID",
    "message": "API Key is invalid"
  },
  "metadata": {
    "requestId": "f6e5d4c3-b2a1-0987-fedc-ba9876543210",
    "executionTimeMs": 1
  }
}
```
```json [Malformed Header]
{
  "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](https://app.reversecontact.com/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 |

> [!TIP]
> Include the `metadata.requestId` from error responses when contacting support. It speeds up troubleshooting.

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](https://docs.reversecontact.com/guides/errors-retries).

## Keep your key safe

Store your key in an environment variable. Never hardcode it:

```bash [macOS / Linux]
export RC_API_KEY="rc_0123456789abcdef0123456789abcdef"
```
```powershell [Windows]
$env:RC_API_KEY = "rc_0123456789abcdef0123456789abcdef"
```
```bash [.env]
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](https://app.reversecontact.com/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.