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

# Authentication

> Authenticate API requests using API keys.

The Ingestly API uses API key authentication. Include your API key in every request using the `X-Api-Key` header.

## API key authentication

```bash theme={null}
X-Api-Key: ing_your_api_key_here
```

API keys use the `ing_` prefix and are created in the [API keys settings](/admin/api-keys) page.

### Example request

```bash theme={null}
curl -X POST "https://api.ingestly.ai/pipelines/3fa85f64-5717-4562-b3fc-2c963f66afa6/trigger" \
  -H "X-Api-Key: ing_your_api_key_here" \
  -F "file=@document.pdf"
```

## Creating API keys

1. Go to **Settings** → **API keys** in the [dashboard](https://ingestly.ai)
2. Click **Create API key**
3. Enter a descriptive name
4. Copy the key immediately. It is only shown once

See [API keys administration](/admin/api-keys) for detailed instructions.

## Key scope

API keys are scoped to your **organization**. A key grants the `ApiKey.Trigger.Create` permission, which allows submitting documents to any active pipeline with a webhook trigger in your organization.

## Authentication errors

| Status code        | Description                                      |
| ------------------ | ------------------------------------------------ |
| `401 Unauthorized` | API key is missing, invalid, or deactivated      |
| `403 Forbidden`    | API key does not have permission for this action |

## Security best practices

* **Never expose keys in client-side code:** API keys should only be used in server-side applications
* **Use environment variables:** store keys in environment variables or a secrets manager, not in source code
* **Rotate keys regularly:** create a new key, update your integration, then delete the old key
* **Use one key per integration:** create separate keys for each application or environment so you can revoke them independently
* **Delete unused keys:** remove keys that are no longer needed to minimize your attack surface