Admin API - Vexa

Manage users and API tokens for your self-hosted Vexa instance. The Admin API is used to create users, mint API tokens, and configure user settings.

Prerequisites

Base URL: http://localhost:8056 (default port from .env)
Admin Token: ADMIN_API_TOKEN=token (default, check your .env file)

For Python examples, install the client:

pip install vexa-client

Before starting, ensure Vexa services are running - see the Deployment Guide for setup instructions. Admin endpoints use /admin/ prefix with X-Admin-API-Key header.

1. Create User

Create a new user or return existing user if email already exists.

Using curl

curl -X POST http://localhost:8056/admin/users \
  -H "Content-Type: application/json" \
  -H "X-Admin-API-Key: token" \
  -d '{
    "email": "user@example.com",
    "name": "John Doe",
    "max_concurrent_bots": 2
  }'

Response:

{
  "id": 1,
  "email": "user@example.com",
  "name": "John Doe",
  "max_concurrent_bots": 2,
  "created_at": "2025-10-10T12:00:00Z"
}

Using Python

from vexa_client import VexaClient

admin_client = VexaClient(
    base_url="http://localhost:8056",
    admin_key="token"
)

user = admin_client.create_user(
    email="user@example.com",
    name="John Doe",
    max_concurrent_bots=2
)

print(f"Created user: {user['email']} (ID: {user['id']})")

Parameters:

email (required): User’s email address
name (optional): User’s display name
max_concurrent_bots (optional): Maximum concurrent bots (default: 0)

2. Create API Token

Generate an API token for a user to access the API.

Using curl

# Replace USER_ID with the user's ID from step 1
curl -X POST http://localhost:8056/admin/users/1/tokens \
  -H "X-Admin-API-Key: token"

Response:

{
  "id": 1,
  "token": "AbCdEf1234567890AbCdEf1234567890AbCdEf12",
  "user_id": 1,
  "created_at": "2025-10-10T12:00:00Z"
}

Using Python

token_info = admin_client.create_token(user_id=user['id'])

print(f"API token: {token_info['token']}")
# Save this token - it cannot be retrieved later!

⚠️ Important: Save the token immediately - it cannot be retrieved later.

Complete Workflow Example

Using curl

# Step 1: Create user
USER_RESPONSE=$(curl -s -X POST http://localhost:8056/admin/users \
  -H "Content-Type: application/json" \
  -H "X-Admin-API-Key: token" \
  -d '{
    "email": "newuser@example.com",
    "name": "New User",
    "max_concurrent_bots": 2
  }')

USER_ID=$(echo $USER_RESPONSE | jq -r '.id')
echo "Created user with ID: $USER_ID"

# Step 2: Generate API token
TOKEN_RESPONSE=$(curl -s -X POST http://localhost:8056/admin/users/${USER_ID}/tokens \
  -H "X-Admin-API-Key: token")

API_TOKEN=$(echo $TOKEN_RESPONSE | jq -r '.token')
echo "Generated token: $API_TOKEN"

# Step 3: Test user API access
curl -X GET "http://localhost:8056/meetings" \
  -H "X-API-Key: $API_TOKEN"

Using Python

from vexa_client import VexaClient

# Step 1: Create user
admin_client = VexaClient(base_url="http://localhost:8056", admin_key="token")

user = admin_client.create_user(
    email="newuser@example.com",
    name="New User",
    max_concurrent_bots=2
)
print(f"✓ Created user: {user['email']}")

# Step 2: Generate token
token_info = admin_client.create_token(user_id=user['id'])
api_token = token_info['token']
print(f"✓ Generated token: {api_token}")

# Step 3: Test user access
user_client = VexaClient(base_url="http://localhost:8056", api_key=api_token)
meetings = user_client.get_meetings()
print(f"✓ User API access working!")

Other User Management Operations

Get User by Email

curl:

curl -X GET "http://localhost:8056/admin/users/email/user@example.com" \
  -H "X-Admin-API-Key: token"

Python:

user = admin_client.get_user_by_email("user@example.com")
print(f"User ID: {user['id']}, Bots: {user['max_concurrent_bots']}")

Get User by ID

curl:

curl -X GET "http://localhost:8056/admin/users/1" \
  -H "X-Admin-API-Key: token"

Returns detailed user information including API tokens.

List All Users

curl:

curl -X GET "http://localhost:8056/admin/users?skip=0&limit=100" \
  -H "X-Admin-API-Key: token"

Python:

users = admin_client.list_users(skip=0, limit=100)
for user in users:
    print(f"{user['email']}: {user['max_concurrent_bots']} bots")

Update User

Update user settings such as concurrent bot limits. curl:

curl -X PATCH http://localhost:8056/admin/users/1 \
  -H "Content-Type: application/json" \
  -H "X-Admin-API-Key: token" \
  -d '{
    "max_concurrent_bots": 5
  }'

Python:

user = admin_client.get_user_by_email("user@example.com")

updated_user = admin_client.update_user(
    user_id=user['id'],
    max_concurrent_bots=5
)

print(f"Updated bot limit to {updated_user['max_concurrent_bots']}")

Updatable Fields:

name: User’s display name
max_concurrent_bots: Maximum concurrent bots
image_url: User’s profile image URL
data: Custom JSONB data (advanced)

Revoke Token

curl:

# Delete token by ID
curl -X DELETE http://localhost:8056/admin/tokens/1 \
  -H "X-Admin-API-Key: token"

Note: Token deletion is immediate and cannot be undone.

Analytics & Monitoring

Meeting & User Stats

Paginated list of all meetings with embedded user details.

curl "http://localhost:8056/admin/stats/meetings-users?skip=0&limit=100" \
  -H "X-Admin-API-Key: token"

Returns { "total": 218, "items": [...] } where each item includes full meeting data and the associated user.

User Analytics

List all users (for dashboard tables).

curl "http://localhost:8056/admin/analytics/users?skip=0&limit=100" \
  -H "X-Admin-API-Key: token"

Meeting Analytics

List all meetings (for dashboard tables).

curl "http://localhost:8056/admin/analytics/meetings?skip=0&limit=100" \
  -H "X-Admin-API-Key: token"

Meeting Telematics

Detailed telemetry for a specific meeting including sessions, transcription stats, and performance metrics.

curl "http://localhost:8056/admin/analytics/meetings/218/telematics" \
  -H "X-Admin-API-Key: token"

Returns { "meeting": {...}, "sessions": [...], "transcription_stats": {...}, "performance_metrics": {...} }.

User Details

Comprehensive user analytics including meeting stats and usage patterns.

curl "http://localhost:8056/admin/analytics/users/1/details?include_tokens=true" \
  -H "X-Admin-API-Key: token"

Parameter	Type	Default	Description
`include_meetings`	bool	`true`	Include meeting history
`include_tokens`	bool	`false`	Include API token list

Returns { "user": {...}, "meeting_stats": {...}, "usage_patterns": {...}, "api_tokens": [...] }.

Webhook Configuration (User-facing)

Admin can also set webhooks for users via PUT /user/webhook on the user API (port 8056) with the user’s API key. See Settings API.

Token Security Best Practices

Secure Distribution: Share tokens via secure channels
Rotate Regularly: For production deployments, rotate tokens periodically
Revoke Compromised Tokens: Immediately delete tokens if compromised
Monitor Usage: Track token usage through meeting logs

Troubleshooting

Common Issues

“Invalid or missing admin token”

Check your .env file for ADMIN_API_TOKEN
Ensure you’re using X-Admin-API-Key header (not X-API-Key)

“User not found”

Verify user was created successfully
Check user ID/email spelling
Use GET /admin/users to list all users

“Connection refused”

Ensure services are running: make ps
Check API Gateway is healthy: curl http://localhost:8056/

Token not working for user API

Verify token was copied correctly
Ensure using X-API-Key header (not X-Admin-API-Key)
Check token wasn’t deleted

Reference Links

API Gateway Docs: http://localhost:8056/docs
Deployment Guide: deployment
Notebooks: nbs/manage_users.ipynb, nbs/0_basic_test.ipynb

Getting Help

Discord: https://discord.gg/Ga9duGkVz9
GitHub Issues: https://github.com/Vexa-ai/vexa/issues

Note: For complete API documentation including bot management and transcription endpoints, see http://localhost:8056/docs

Documentation Index

​Prerequisites

​1. Create User

​Using curl

​Using Python

​2. Create API Token

​Using curl

​Using Python

​Complete Workflow Example

​Using curl

​Using Python

​Other User Management Operations

​Get User by Email

​Get User by ID

​List All Users

​Update User

​Revoke Token

​Analytics & Monitoring

​Meeting & User Stats

​User Analytics

​Meeting Analytics

​Meeting Telematics

​User Details

​Webhook Configuration (User-facing)

​Token Security Best Practices

​Troubleshooting

​Common Issues

​Reference Links

​Getting Help

Prerequisites

1. Create User

Using curl

Using Python

2. Create API Token

Using curl

Using Python

Complete Workflow Example

Using curl

Using Python

Other User Management Operations

Get User by Email

Get User by ID

List All Users

Update User

Revoke Token

Analytics & Monitoring

Meeting & User Stats

User Analytics

Meeting Analytics

Meeting Telematics

User Details

Webhook Configuration (User-facing)

Token Security Best Practices

Troubleshooting

Common Issues

Reference Links

Getting Help