Skip to main content

​
Authentication

All API requests require authentication using your API key plus three identifying headers.

​
API Key

Your API key is provided by DocBit AI and looks like: 
sk_yourpartner_a1b2c3d4e5f6g7h8i9j0...
Include it in the Authorization header: 
Authorization: ApiKey sk_yourpartner_a1b2c3d4e5f6g7h8i9j0...
Never expose your API key in client-side code or commit it to version control.

​
Required Headers

Every request must include these three headers:

​
X-External-Org-Id

Identifies which of your client organizations this request is for. 
X-External-Org-Id: acme
Purpose: Isolates documents and data between your different clients. Example values: acme, beta-corp, client-123

​
X-External-User-Id

Identifies the specific user making the request. 
X-External-User-Id: user-456
Purpose:
  • Enables per-user usage tracking
  • Each user gets their own conversation history
  • Allows per-user billing
Example values: user-456, [email protected], u_abc123

​
X-External-Roles

A JSON array of roles assigned to this user. 
X-External-Roles: ["hr", "manager"]
Purpose: Controls which documents the user can access based on role-based permissions. Format: JSON array of strings, or comma-separated values Example values:
  • ["employee"]
  • ["hr", "manager", "all-staff"]
  • hr,manager (alternative format)

​
Complete Example

POST /api/ai/chat HTTP/1.1
Host: api.docbit.ai
Authorization: ApiKey sk_yourpartner_a1b2c3d4e5f6g7h8i9j0...
X-External-Org-Id: acme
X-External-User-Id: user-456
X-External-Roles: ["hr", "manager"]
Content-Type: application/json

{
  "message": "What are the benefits offered?"
}

​
Error Responses

StatusErrorSolution
400Missing required header: X-External-Org-IdInclude the header
400Missing required header: X-External-User-IdInclude the header
400Missing required header: X-External-RolesInclude the header
400At least one role is requiredProvide at least one role
401Invalid API keyCheck your API key
401API key is inactiveContact support
401API key has expiredContact support

​
Best Practices

Use environment variables or a secrets manager. Never hardcode the key.
Use the same org ID and user ID consistently. These create user accounts that persist conversations.
Only pass roles the user actually has. Don’t give everyone admin access.
Implement retry logic for transient failures. Don’t expose raw error messages to end users.

​
Key Rotation

If your API key is compromised:
  1. Contact DocBit AI support immediately
  2. We will generate a new key
  3. Update your application with the new key
  4. The old key will be deactivated

​
Next Steps