Authentication

DokuBrain supports two authentication methods: API keys for server-to-server integrations, and JWT tokens for user-facing applications.

API keys

API keys are the recommended way to authenticate programmatic API access. Each key is scoped to an organization and inherits the permissions of the user who created it.

Creating an API key

1. Log in to the DokuBrain dashboard
2. Navigate to Settings → Integrations
3. Click Create API Key
4. Give it a descriptive name (e.g., "Production Backend")
5. Copy the key — it won't be shown again

Using API keys

Include the API key in the Authorization header:

curl https://api.dokubrain.com/api/v1/documents \
  -H "Authorization: Bearer dk_live_abc123..."

API keys use the dk_live_ prefix for production and dk_test_ for sandbox environments.

JWT tokens

For user-facing applications, authenticate users with email/password to obtain a JWT token pair (access token + refresh token).

Login

curl -X POST https://api.dokubrain.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "eyJhbGciOi...",
    "expiresIn": 900
  }
}

Using the access token

Include the access token in the Authorization header:

curl https://api.dokubrain.com/api/v1/documents \
  -H "Authorization: Bearer eyJhbGciOi..."

Access tokens expire after 15 minutes. Use the refresh token to obtain a new access token:

curl -X POST https://api.dokubrain.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOi..."
  }'

Base URL

All API requests should be made to:

Error responses

Authentication errors return a 401 Unauthorized status:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token"
  }
}

Rate limits

Rate-limited responses return 429 Too Many Requests with a Retry-After header.