Skip to main content

​
Organization IDs

The X-External-Org-Id header identifies which of your client organizations a request belongs to. This is the foundation of DocBit AI’s multi-tenant isolation.

​
What is an Organization ID?

An organization ID is a string you provide that uniquely identifies one of your clients. Each organization gets:
  • Isolated document storage - Documents are completely separate between orgs
  • Separate user accounts - The same user ID in different orgs are different users
  • Independent conversation history - Chat history doesn’t cross org boundaries
  • Separate usage tracking - Billing and analytics per organization

​
How It Works

With a single API key, you can serve multiple client organizations. The X-External-Org-Id header determines which tenant’s data is accessed.

​
Choosing Organization IDs

Use identifiers that are:
  • Unique - Each client needs a distinct ID
  • Stable - Don’t change IDs after creation (user data would be orphaned)
  • Meaningful - Easy for you to map back to your clients

​
Good Examples

Your SystemOrganization ID
Database IDorg_12345
Slugacme-corp
Domainacme.com
UUID550e8400-e29b-41d4-a716-446655440000

​
Bad Examples

Don’t UseWhy
User’s nameNot unique, can change
EmailCan change, may not be unique to org
Incrementing numberEasy to guess, enumerate

​
One API Key, Multiple Organizations

Your single partner API key can access all your client organizations: 
const API_KEY = process.env.DOCBIT_API_KEY;

// Query for Acme Corp
await chat({
  headers: {
    'Authorization': `ApiKey ${API_KEY}`,
    'X-External-Org-Id': 'acme',
    'X-External-User-Id': 'user-123',
    'X-External-Roles': '["employee"]'
  },
  body: { message: 'What is our policy?' }
});

// Query for Beta Inc (same API key, different org)
await chat({
  headers: {
    'Authorization': `ApiKey ${API_KEY}`,
    'X-External-Org-Id': 'beta-inc',
    'X-External-User-Id': 'user-456',
    'X-External-Roles': '["employee"]'
  },
  body: { message: 'What is our policy?' }
});

​
Organization Lifecycle

​
Creating Organizations

Organizations are created implicitly on first use. When you send a request with a new X-External-Org-Id, the organization is automatically created. 
# This creates the "new-client" org if it doesn't exist
curl -X POST https://api.docbit.ai/api/documents/upload \
  -H "Authorization: ApiKey sk_..." \
  -H "X-External-Org-Id: new-client" \
  -H "X-External-User-Id: admin" \
  -H "X-External-Roles: [\"admin\"]" \
  -F "[email protected]"

​
Data Isolation

Documents uploaded to one organization are never visible to another: 
Organization "acme":
  └── employee-handbook.pdf
  └── hr-policies.pdf

Organization "beta-corp":
  └── company-guidelines.pdf
  └── benefits.pdf
A user in “acme” asking about policies will only see results from acme’s documents, even if beta-corp has similar documents.

​
Best Practices

Map org IDs to your existing customer/tenant IDs for easy correlation.
Org IDs are internal identifiers. Users don’t need to see them.
Ensure users can only access organizations they belong to in your system.
If you ever need to rename or merge organizations, contact support.

​
Next Steps