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

# Authenticate with the Shilo API Using API Keys

> All Shilo API requests require an API key. Learn how to generate one, pass it in requests, and understand read-only vs. read-write key permissions.

Every request to the Shilo API must include a valid API key. Each key is scoped to a single Shilo integration within your organization, so it can only access data belonging to that integration. Keys also carry either read-only or read-write permissions, so you can issue tightly scoped credentials to third-party tools without granting unnecessary access.

## Generating an API Key

API keys are created in the Shilo web app. You must be an **owner** or **admin** to generate them.

1. Open **Settings** in the Shilo app.
2. Navigate to **API Keys**.
3. Click **Generate API Key**, give it a descriptive name, select the integration the key should be scoped to, and choose its permission level.
4. Copy the key immediately—it will not be shown again.

## Sending Your API Key

You can authenticate using either of two header formats. Both are accepted on every endpoint.

### Option 1 — `x-api-key` header (recommended)

```bash theme={null}
curl https://api.shilo.ai/api/v1/users \
  -H "x-api-key: YOUR_API_KEY"
```

### Option 2 — `Authorization: Bearer` header

```bash theme={null}
curl https://api.shilo.ai/api/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Both headers carry the same key value. Use whichever format fits your HTTP client or SDK most naturally.

## Read-Only vs. Read-Write Keys

Shilo issues two permission tiers:

| Key type       | Allowed methods                | Blocked methods         |
| -------------- | ------------------------------ | ----------------------- |
| **Read-only**  | `GET`                          | `POST`, `PUT`, `DELETE` |
| **Read-write** | `GET`, `POST`, `PUT`, `DELETE` | —                       |

A read-only key attempting a write operation receives a `403 Forbidden` response. This lets you safely hand a key to a reporting dashboard or analytics pipeline without risking accidental data changes.

## Error Responses

| Status             | Meaning                                                          |
| ------------------ | ---------------------------------------------------------------- |
| `401 Unauthorized` | The API key is missing from the request or is invalid.           |
| `403 Forbidden`    | The API key is read-only and the endpoint requires write access. |

A `401` response typically means the key was not included in the header, was mistyped, or has been revoked. Double-check both the header name and the key value.

## Complete Authentication Example

The following request lists the users belonging to the key's integration, using the `x-api-key` header:

```bash theme={null}
curl https://api.shilo.ai/api/v1/users \
  -H "x-api-key: YOUR_API_KEY"
```

The same request using the `Authorization` header:

```bash theme={null}
curl https://api.shilo.ai/api/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<Note>
  Keep your API keys secret. Never embed them in client-side JavaScript, mobile app binaries, or public repositories. Store keys in environment variables or a secrets manager, and rotate them regularly to limit exposure if a key is compromised.
</Note>

## Security Best Practices

* **Use separate keys per integration.** Isolate credentials so you can revoke a single key without disrupting other systems.
* **Prefer read-only keys** for any integration that only needs to read data.
* **Rotate keys periodically.** Generate a replacement key, update your integration, then delete the old key.
* **Audit key usage.** Check the Shilo Settings page regularly for keys that are no longer in use and revoke them.