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

# Authentication

> Authenticate your requests with an API key.

Every request to the Kalent API must include your workspace API key. You can pass it in one of two ways:

<Tabs>
  <Tab title="x-api-key header (recommended)">
    ```bash theme={null}
    curl -X POST https://app.kalent.ai/api/v1/search/talents \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"filters": []}'
    ```
  </Tab>

  <Tab title="Bearer token">
    ```bash theme={null}
    curl -X POST https://app.kalent.ai/api/v1/search/talents \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"filters": []}'
    ```
  </Tab>
</Tabs>

## Get your API key

1. Log in to the [Kalent dashboard](https://app.kalent.ai).
2. Navigate to your workspace settings.
3. Open the **API Keys** section.
4. Click **Create API Key** and copy the generated secret.

<Warning>
  Store your API key securely. Do not commit it to version control or expose it
  in client-side code.
</Warning>

## Error responses

All REST API errors use the same envelope:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human-readable message",
    "debugTrackingCode": "..."
  }
}
```

| Status | `error.code`            | Meaning                                                                                           |
| ------ | ----------------------- | ------------------------------------------------------------------------------------------------- |
| `401`  | `missing_api_key`       | No key was provided in the request.                                                               |
| `401`  | `invalid_api_key`       | The key does not match any active workspace key, or the OAuth access token is invalid or expired. |
| `402`  | `plan_upgrade_required` | The workspace must subscribe to Kalent or upgrade its plan before using this API capability.      |
| `429`  | `rate_limit_exceeded`   | IP-level or API-key-level rate limit exceeded.                                                    |

Subscription and plan errors include an actionable `details` object:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "plan_upgrade_required",
    "message": "A Kalent subscription or plan upgrade is required to create sourcings. Please subscribe or upgrade your plan in Kalent billing: https://app.kalent.ai/settings/billing",
    "debugTrackingCode": "...",
    "details": {
      "code": "subscription_or_plan_upgrade_required",
      "action": "subscribe_or_upgrade",
      "capability": "create_sourcings",
      "billingUrl": "https://app.kalent.ai/settings/billing"
    }
  }
}
```