> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recoverbiz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with the Recover Partner API.

## Partner API Key

All Partner API requests require a **Partner API Key** passed in the request header.

```
X-Partner-Key: pk_live_abc123def456...
```

Or as a Bearer token:

```
Authorization: Bearer pk_live_abc123def456...
```

## Getting a Partner API Key

Partner API keys are provisioned during onboarding. Contact your Recover account manager or email [adyan@cove.dev](mailto:adyan@cove.dev). Each key is scoped to your partner account and grants access to all sub-accounts under it.

## Key Format

Keys follow the format `pk_live_` followed by 32 characters. Keep your key secret — it grants full access to create and manage accounts, import leads, and generate embed tokens.

<Warning>
  Never expose your Partner API key in client-side code. All API calls should be made from your backend server.
</Warning>

## Key Rotation

To rotate a key, contact your account manager. The old key will remain valid for 24 hours after the new key is issued.

## Rate Limits

| Endpoint               | Limit                    |
| ---------------------- | ------------------------ |
| Account creation       | 100 / hour               |
| Lead import (single)   | 1,000 / minute           |
| Lead import (bulk)     | 50 / minute              |
| Embed token generation | 500 / hour               |
| Conversation reads     | 5,000 / minute           |
| Message sends          | 100 / minute per account |
| All other endpoints    | 1,000 / minute           |

Rate limit headers are included in every response:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1771200000
```

When rate limited, the API returns `429 Too Many Requests` with a `Retry-After` header.

## Error Format

All errors follow a consistent format:

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing Partner API key",
    "status": 401
  }
}
```

### Error Codes

| Code                  | Status | Description                                |
| --------------------- | ------ | ------------------------------------------ |
| `unauthorized`        | 401    | Invalid or missing Partner API key         |
| `forbidden`           | 403    | Key does not have access to this resource  |
| `not_found`           | 404    | Account, lead, or resource not found       |
| `invalid_phone`       | 400    | Phone number format is invalid             |
| `duplicate_lead`      | 409    | Lead with this external\_id already exists |
| `account_deactivated` | 403    | Account has been deactivated               |
| `token_expired`       | 401    | Embed token has expired                    |
| `rate_limited`        | 429    | Too many requests                          |
| `validation_error`    | 422    | Request body failed validation             |
| `internal_error`      | 500    | Internal server error                      |