> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/lumina-ai-inc/chunkr/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate your requests to the Chunkr API

The Chunkr API uses API keys to authenticate requests. All API endpoints under `/api/v1` require authentication.

## Authentication Methods

Chunkr supports two authentication methods:

1. **API Key Authentication** (Recommended)
2. **Bearer Token Authentication** (OAuth/Keycloak)

## API Key Authentication

### Getting Your API Key

API keys can be generated and managed through your Chunkr account dashboard. Each API key is associated with your user account and inherits your permissions.

### Using API Keys

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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.chunkr.ai/api/v1/task/parse \
    -H "Authorization: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "file": "base64_encoded_file_data",
      "ocr_strategy": "Auto"
    }'
  ```

  ```python Python theme={null}
  import requests

  headers = {
      "Authorization": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  response = requests.post(
      "https://api.chunkr.ai/api/v1/task/parse",
      headers=headers,
      json={
          "file": "base64_encoded_file_data",
          "ocr_strategy": "Auto"
      }
  )
  ```

  ```javascript JavaScript theme={null}
  fetch('https://api.chunkr.ai/api/v1/task/parse', {
    method: 'POST',
    headers: {
      'Authorization': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      file: 'base64_encoded_file_data',
      ocr_strategy: 'Auto'
    })
  });
  ```
</CodeGroup>

<Warning>
  Never share your API key or commit it to version control. Store it securely in environment variables or a secrets manager.
</Warning>

### API Key Requirements

For API key authentication to succeed:

* The API key must exist in the database
* The API key must be marked as `active = true`
* The API key must not be marked as `deleted = true`
* The key must be associated with a valid user account

## Bearer Token Authentication

For applications using OAuth/Keycloak authentication, you can use Bearer tokens:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.chunkr.ai/api/v1/task/parse \
    -H "Authorization: Bearer YOUR_JWT_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "file": "base64_encoded_file_data"
    }'
  ```

  ```python Python theme={null}
  import requests

  headers = {
      "Authorization": "Bearer YOUR_JWT_TOKEN",
      "Content-Type": "application/json"
  }

  response = requests.post(
      "https://api.chunkr.ai/api/v1/task/parse",
      headers=headers,
      json={"file": "base64_encoded_file_data"}
  )
  ```
</CodeGroup>

### Token Validation

Bearer tokens are validated using RS256 algorithm against the Keycloak JWKS endpoint. The token must:

* Be a valid JWT signed with RS256
* Contain a `sub` (subject) claim with the user ID
* Be issued by the configured Keycloak realm

### Token Claims

The following JWT claims are extracted and used:

* `sub` - User ID (required)
* `email` - User email address
* `given_name` - User's first name
* `family_name` - User's last name

## CORS and Pre-flight Requests

<Note>
  OPTIONS requests (CORS pre-flight) are automatically allowed and do not require authentication.
</Note>

The API uses permissive CORS settings to allow requests from web applications. Pre-flight OPTIONS requests bypass authentication middleware.

## Authentication Errors

### Missing Authorization Header

**Status Code**: `401 Unauthorized`

**Response**:

```
Authorization header is missing
```

This error occurs when you don't include the `Authorization` header in your request.

### Invalid API Key

**Status Code**: `401 Unauthorized`

**Response**:

```
Invalid or inactive API key
```

This error occurs when:

* The API key doesn't exist
* The API key is marked as inactive
* The API key has been deleted

### Invalid Bearer Token

**Status Code**: `401 Unauthorized`

**Response**:

```
Invalid token payload
```

This error occurs when:

* The JWT token is malformed
* The token signature is invalid
* The token is expired
* The token is not signed with RS256

### Missing API Key

**Status Code**: `401 Unauthorized`

**Response**:

```
API key is missing
```

This error occurs when the Authorization header is present but empty.

## Security Best Practices

1. **Rotate Keys Regularly**: Generate new API keys periodically and revoke old ones
2. **Use Environment Variables**: Never hardcode API keys in your application
3. **Limit Key Scope**: Use different API keys for different environments (dev, staging, production)
4. **Monitor Usage**: Regularly review your API key usage for unusual activity
5. **Secure Storage**: Store API keys in secure secret management systems

## User Context

Once authenticated, the API attaches user information to the request context, including:

* User ID
* Email address
* First and last name
* API key used (if applicable)

This information is used for:

* Task ownership and isolation
* Usage tracking and billing
* Audit logging

## Next Steps

<CardGroup cols={2}>
  <Card title="Error Handling" icon="triangle-exclamation" href="/api/errors">
    Learn about error responses and how to handle them
  </Card>

  <Card title="Create a Task" icon="play" href="/api/endpoints/task">
    Start processing documents with the Task API
  </Card>
</CardGroup>