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:

cURL

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"
  }'

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

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:

cURL

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"
  }'

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

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

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

Error Handling

Learn about error responses and how to handle them

Create a Task

Start processing documents with the Task API