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

# authentication

> Invoke uses API keys to authenticate requests. Learn how to get your API key, pass it in requests, and handle authentication errors.

Invoke uses API keys to authenticate every request. Your key identifies your account and must be included in all SDK calls and direct API requests.

## Get your API key

Find your API key in the [Invoke dashboard](https://invokehq.run) under **Settings → API Keys**.

## Passing your API key

### SDK

The `@invoke/sdk` package reads `INVOKE_API_KEY` automatically from `process.env`:

```typescript theme={null}
import { Invoke } from "@invoke/sdk"

const invoke = new Invoke({
  apiKey: process.env.INVOKE_API_KEY!,
})
```

### Direct API requests

Send your key as the `X-API-Key` header:

```bash theme={null}
curl -X POST https://api.invokehq.run/outcomes/reconcile \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

Or as a query parameter (less preferred):

```bash theme={null}
https://api.invokehq.run/outcomes/reconcile?api_key=your_api_key
```

## Environment variable

Set your key in your environment or `.env` file:

```bash theme={null}
INVOKE_API_KEY=your_api_key
```

See [Environment Variables](/configuration/environment-variables) for all variables the SDK and CLI read.

## Authentication errors

| Error              | Cause                             | Fix                                   |
| ------------------ | --------------------------------- | ------------------------------------- |
| `401 Unauthorized` | Missing or invalid API key        | Check the key is set and correct      |
| `403 Forbidden`    | Key is valid but lacks permission | Check your account plan and key scope |

The SDK throws before making any network call if `apiKey` is missing or empty.

## Next steps

* [Environment Variables](/configuration/environment-variables) — all configuration variables
* [Quick Start](/quickstart) — end-to-end setup including authentication