Skip to main content

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.

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 -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 -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

Build docs developers (and LLMs) love

Get started for freeTalk to us