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

# Authentication

> Learn how to authenticate with the FoxReach API using API keys.

## API Key Authentication

The FoxReach API uses API keys to authenticate requests. All API requests must include your API key in the `X-API-Key` header.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.foxreach.io/api/v1/leads \
    -H "X-API-Key: otr_your_api_key_here"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.foxreach.io/api/v1/leads",
      headers={"X-API-Key": "otr_your_api_key_here"}
  )
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.foxreach.io/api/v1/leads",
    { headers: { "X-API-Key": "otr_your_api_key_here" } }
  );
  ```
</CodeGroup>

## Creating an API Key

<Steps>
  <Step title="Navigate to Settings">
    Open the [dashboard](https://www.foxreach.io) and go to **Settings > API Keys**.
  </Step>

  <Step title="Create a new key">
    Click **Create API Key**, give it a descriptive name (e.g., "CRM Integration"), and select the scopes you need.
  </Step>

  <Step title="Copy your key">
    Your full API key is shown **only once** after creation. Copy it and store it securely.
  </Step>
</Steps>

<Warning>
  Your API key is shown only once at creation time. If you lose it, you'll need to create a new one.
</Warning>

## Key Format

API keys follow the format `otr_` followed by a random string:

```
otr_a1b2c3d4e5f6g7h8i9j0...
```

The `otr_` prefix helps you identify FoxReach API keys in your codebase.

## Scopes

Each API key has one or more scopes that control what actions it can perform:

| Scope   | Description                                                                    |
| ------- | ------------------------------------------------------------------------------ |
| `read`  | Read access to all resources (leads, campaigns, accounts, templates, webhooks) |
| `write` | Create, update, and delete resources                                           |

By default, new keys are created with both `read` and `write` scopes.

## Workspace Scoping

API keys are scoped to a specific workspace. All resources accessed through an API key are limited to that workspace's data. This means:

* A key created in Workspace A cannot access data in Workspace B
* Resources created via the API are automatically assigned to the key's workspace

## Security Best Practices

<AccordionGroup>
  <Accordion title="Never expose keys in client-side code">
    API keys should only be used in server-side code. Never include them in JavaScript bundles, mobile apps, or any code that runs in the browser.
  </Accordion>

  <Accordion title="Use environment variables">
    Store your API key in environment variables rather than hardcoding it:

    ```bash theme={null}
    export FOXREACH_API_KEY="otr_your_key_here"
    ```

    ```python theme={null}
    import os
    api_key = os.environ["FOXREACH_API_KEY"]
    ```
  </Accordion>

  <Accordion title="Rotate keys regularly">
    Create new keys periodically and revoke old ones. You can have multiple active keys at once to enable zero-downtime rotation.
  </Accordion>

  <Accordion title="Use least-privilege scopes">
    If your integration only needs to read data, create a key with only the `read` scope.
  </Accordion>
</AccordionGroup>

## Error Responses

If authentication fails, the API returns a `401` error:

```json theme={null}
{
  "detail": "Invalid API key"
}
```

Common causes:

* Missing `X-API-Key` header
* Invalid or revoked API key
* Expired API key

If your key is valid but lacks the scope required by the endpoint, the API returns a `403` error instead:

```json theme={null}
{
  "detail": "API key does not have the required scope: write"
}
```