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

# Authentication

> How to authenticate with the Hostreach API using API keys.

## API keys

All requests to the Hostreach public API must include an API key. Keys are scoped, revocable, and prefixed to indicate the environment.

### Generate a key

1. Log in at [app.hostreach.io](https://app.hostreach.io).
2. Go to **Settings › Workspace › Acceso API**.
3. Click **New API key**, choose a name, environment, and scopes.
4. Copy the key — **it is only shown once**.

### Key format

| Environment | Prefix     | Example                |
| ----------- | ---------- | ---------------------- |
| Live        | `hr_live_` | `hr_live_a1b2c3d4_...` |
| Test        | `hr_test_` | `hr_test_a1b2c3d4_...` |

Use `hr_live_` keys for production integrations and `hr_test_` keys for development and testing.

## Sending the key

You can pass the key in either of two ways:

### Option 1 — X-Api-Key header (recommended)

```bash theme={null}
curl https://api.hostreach.io/v1/public/v1/me \
  -H "X-Api-Key: hr_live_your_key_here"
```

### Option 2 — Bearer token

```bash theme={null}
curl https://api.hostreach.io/v1/public/v1/me \
  -H "Authorization: Bearer hr_live_your_key_here"
```

## Scopes

API keys can be restricted to specific scopes. An empty `scopes` array means **full access** (wildcard).

| Scope                        | Access granted                              |
| ---------------------------- | ------------------------------------------- |
| `campaigns:read` / `write`   | List, create, update campaigns              |
| `leads:read` / `write`       | List, update, delete leads and notes        |
| `extractions:read` / `write` | Start and inspect extraction jobs           |
| `platforms:read`             | Platform filter schemas and location search |
| `messaging:read` / `write`   | Read/send WhatsApp messages                 |
| `templates:read` / `write`   | Message templates                           |
| `accounts:read` / `write`    | WhatsApp accounts                           |
| `valuations:read` / `write`  | Property valuations                         |
| `fichas:read` / `write`      | Listing sheets                              |
| `scheduling:read` / `write`  | Event types and appointments                |
| `webhooks:read` / `write`    | Webhook subscriptions                       |

A `403 Forbidden` response means the key is valid but lacks the required scope for that endpoint. Create a new key with the necessary scope.

## Error responses

All errors return a JSON body:

```json theme={null}
{
  "statusCode": 401,
  "message": "Invalid or missing API key"
}
```

| Status | Cause                                |
| ------ | ------------------------------------ |
| `401`  | Missing or invalid API key           |
| `403`  | Key valid but missing required scope |
| `429`  | Rate or quota limit reached          |

## Key rotation and revocation

* To rotate a key: create a new key, update your integration, then revoke the old one.
* To revoke: go to **Settings › Workspace › Acceso API** and click **Revoke** next to the key.
* Revoked keys return `401` immediately.