Skip to main content

​
User IDs

The X-External-User-Id header identifies the specific user making a request. This enables per-user features like conversation history and usage tracking.

​
What is a User ID?

A user ID is a string you provide that uniquely identifies a user within an organization. Each user gets:
  • Personal conversation history - Their chat sessions are preserved
  • Individual usage tracking - Analytics and billing per user
  • Separate context - Conversations don’t mix between users

​
How It Works

Each user has their own set of conversations. When Alice asks a follow-up question, she sees her previous messages. Bob sees only his own history.

​
Choosing User IDs

Use identifiers that are:
  • Unique within each org - Two users in the same org need different IDs
  • Stable - Don’t change after creation
  • Tied to your user system - Easy to map to your users

​
Good Examples

Your SystemUser ID
Database IDuser_12345
UUID550e8400-e29b-41d4-a716-446655440000
Email[email protected]
Usernamealice.smith

​
Same User ID, Different Orgs

The same user ID in different organizations are separate users: 
Organization "acme":
  └── User "alice" → Alice at Acme Corp
  
Organization "beta-corp":
  └── User "alice" → Different Alice at Beta Inc
This is by design - it allows you to use simple user identifiers without worrying about global uniqueness.

​
Per-User Conversation History

Users automatically get persistent conversation history: 
// Alice's first message - creates new conversation
const response1 = await chat({
  headers: {
    'X-External-Org-Id': 'acme',
    'X-External-User-Id': 'alice',
    'X-External-Roles': '["employee"]'
  },
  body: { message: 'What is our vacation policy?' }
});

// Alice's follow-up - continues the conversation
const response2 = await chat({
  headers: {
    'X-External-Org-Id': 'acme',
    'X-External-User-Id': 'alice',
    'X-External-Roles': '["employee"]'
  },
  body: { 
    message: 'How do I request time off?',
    conversationId: response1.conversationId
  }
});

​
Per-User Usage Tracking

Track usage at the individual user level: 
{
  "totalRequests": 150,
  "uniqueUsers": 25,
  "breakdown": [
    { "userId": "alice", "requests": 45, "tokens": 12000 },
    { "userId": "bob", "requests": 30, "tokens": 8500 }
  ]
}
This enables:
  • Per-seat billing - Charge based on active users
  • Usage analytics - Understand adoption patterns
  • Audit trails - Track who accessed what

​
User Lifecycle

​
User Creation

Users are created implicitly on first request: 
# Creates user "new-user" in org "acme" if they don't exist
curl -X POST https://api.docbit.ai/api/ai/chat \
  -H "X-External-Org-Id: acme" \
  -H "X-External-User-Id: new-user" \
  -H "X-External-Roles: [\"employee\"]" \
  -d '{"message": "Hello"}'

​
Mapping to Your Users

A common pattern is to use your authentication system to populate the header: 
// Express middleware example
function DocBit AIContext(req, res, next) {
  const user = req.session.user; // Your authenticated user
  
  req.DocBit AIHeaders = {
    'X-External-Org-Id': user.organizationId,
    'X-External-User-Id': user.id,          // Your user's ID
    'X-External-Roles': JSON.stringify(user.roles)
  };
  
  next();
}

​
Best Practices

Map to your authentication system’s user IDs for easy correlation.
Changing a user’s ID would orphan their conversation history.
While emails work, consider using opaque IDs for privacy.
Ensure users can only access organizations they belong to in your system.

​
Next Steps