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

# Authenticate InferenceWall API Requests

> InferenceWall uses API key authentication with scan and admin roles. Generate keys, pass them as Authorization: Bearer, and follow security best practices.

InferenceWall authenticates requests using API keys with two distinct roles: `scan` for scanning and analysis endpoints, and `admin` for management and configuration endpoints. You pass the key in the `Authorization` header of every request.

## Dev mode

<Note>
  If the `IW_API_KEY` environment variable is not set, authentication is disabled entirely. This is convenient for local development, but you must enable auth before deploying to production.
</Note>

## Generating keys

Run the setup command to generate both a scan key and an admin key:

```bash theme={null}
inferwall admin setup
```

This writes the generated keys to `.env.local` in your working directory. Source the file to load them into your environment:

```bash theme={null}
source .env.local
```

Keys use the following format:

| Key type | Prefix       | Example                     |
| -------- | ------------ | --------------------------- |
| Scan     | `iwk_scan_`  | `iwk_scan_a1b2c3d4e5f6...`  |
| Admin    | `iwk_admin_` | `iwk_admin_a1b2c3d4e5f6...` |

## Passing the key

Include your API key in the `Authorization: Bearer` header on every request:

```bash theme={null}
curl -X POST http://localhost:8000/v1/scan/input \
  -H "Authorization: Bearer iwk_scan_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "user input"}'
```

## Key roles

Each key type grants access to a specific set of endpoints:

| Key type | Prefix       | Can access                                                                                  |
| -------- | ------------ | ------------------------------------------------------------------------------------------- |
| Scan     | `iwk_scan_`  | `/v1/scan/*`, `/v1/analyze/*`, `/v1/health/*`, `/v1/signatures` (read-only), `/v1/sessions` |
| Admin    | `iwk_admin_` | All endpoints, including `/v1/admin/*`, `/v1/auth/*`, `/v1/config`, and all scan endpoints  |

<Tip>
  Use the scan key in your application code. Reserve the admin key for management scripts and CI pipelines.
</Tip>

## Auth endpoints

### POST /v1/auth/login

Log in with your admin key. On success, InferenceWall sets an `httpOnly` session cookie that you can use for subsequent requests.

**Request body:**

<ParamField body="key" type="string" required>
  Your admin API key (`iwk_admin_` prefix).
</ParamField>

```bash theme={null}
curl -X POST http://localhost:8000/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"key": "iwk_admin_YOUR_KEY"}'
```

***

### POST /v1/auth/logout

Clear the current session cookie.

```bash theme={null}
curl -X POST http://localhost:8000/v1/auth/logout
```

***

### GET /v1/auth/check

Check whether the current session cookie is valid.

```bash theme={null}
curl http://localhost:8000/v1/auth/check
```

## Error responses

When a request is made without a valid key or session, the API returns `401 Unauthorized`:

```json theme={null}
{
  "detail": "Unauthorized"
}
```

## Security best practices

<Warning>
  Never commit API keys to source control. Use environment variables or a secrets manager.
</Warning>

* Enable TLS in production by setting `IW_TLS=auto`. This uses automatic certificate management via ACME.
* Rotate keys regularly and revoke any that are no longer in use.
* Scope your application's key to the minimum required role — use `iwk_scan_` keys in application code and reserve `iwk_admin_` keys for management operations.