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

# Authentication

> Authenticate your API requests with Bearer tokens

## Bearer Token Authentication

All API requests must include a valid API key in the `Authorization` header:

```http theme={null}
Authorization: Bearer river_live_xxxxxxxxxxxxx
```

## API Key Format

API keys follow the pattern:

```
river_{environment}_{random32}
```

| Prefix        | Environment | Usage                                   |
| ------------- | ----------- | --------------------------------------- |
| `river_live_` | Production  | Live API calls, charged to your account |
| `river_test_` | Sandbox     | Testing, no charges incurred            |

## Managing API Keys

### Create a Key

Create API keys from the [Dashboard](https://modelhunter.ai/dashboard/api-keys) or via the API:

```bash theme={null}
curl -X POST https://api.modelhunter.ai/api/v1/api-keys \
  -H "Authorization: Bearer river_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Backend",
    "spendLimit": 1000,
    "expiresAt": "2027-01-01T00:00:00Z"
  }'
```

<Warning>
  The full API key is only shown once at creation time. Store it securely — you cannot retrieve it later.
</Warning>

### Rotate a Key

To rotate a key, create a new one, update your application, then delete the old key.

### Delete a Key

```bash theme={null}
curl -X DELETE https://api.modelhunter.ai/api/v1/api-keys/{key_id} \
  -H "Authorization: Bearer river_live_xxx"
```

## Permissions

Each API key can be scoped with fine-grained permissions:

| Permission    | Description                              | Example                    |
| ------------- | ---------------------------------------- | -------------------------- |
| `permissions` | Permission object restricting key access | `{ "video:create": true }` |
| `ipWhitelist` | IP addresses allowed to use this key     | `["203.0.113.50"]`         |
| `spendLimit`  | Maximum spend limit in USD               | `1000`                     |

When no permissions are set, the key has full access to all providers and types.

## Security Best Practices

<AccordionGroup>
  <Accordion title="Use environment variables">
    Never hardcode API keys in your source code.

    ```bash theme={null}
    # .env
    MODELHUNTER_KEY=river_live_xxxxxxxxxxxxx
    ```

    ```javascript theme={null}
    const response = await fetch('https://api.modelhunter.ai/api/v1/...', {
      headers: {
        'Authorization': `Bearer ${process.env.MODELHUNTER_KEY}`,
      },
    });
    ```
  </Accordion>

  <Accordion title="Never commit keys to Git">
    Add `.env` to your `.gitignore` file. If a key is accidentally committed, rotate it immediately from the Dashboard.
  </Accordion>

  <Accordion title="Use scoped keys">
    Create separate keys for different environments and services. Scope each key to only the providers and types it needs.
  </Accordion>

  <Accordion title="Set spend limits">
    Use `spendLimit` to cap usage per key and prevent unexpected charges.
  </Accordion>
</AccordionGroup>

## Error Responses

| Status | Code                    | Description                    |
| ------ | ----------------------- | ------------------------------ |
| 401    | `AUTH_REQUIRED`         | No API key provided            |
| 401    | `AUTH_INVALID_TOKEN`    | Invalid or malformed API key   |
| 401    | `AUTH_TOKEN_EXPIRED`    | API key has expired            |
| 403    | `KEY_PERMISSION_DENIED` | Key lacks required permissions |
| 403    | `KEY_REVOKED`           | Key has been deleted           |