Skip to main content

User Management Guide

Learn how to manage users, assign roles, create teams, and configure permissions.

Creating Users​

POST /api/v1/users
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "email": "agent@example.com",
  "name": "John Smith",
  "role": "agent",
  "teams": ["support_team"],
  "send_invitation": true
}

Role Hierarchy​

RoleDescriptionTypical Permissions
super_adminOrganization ownerAll permissions
adminIT administratorUser/role management
supervisorTeam leadTeam management, reports
agentCall center agentHandle calls/tickets
viewerRead-only accessView reports only

Managing Roles​

List Roles​

GET /api/v1/roles

Create Custom Role​

POST /api/v1/roles
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "name": "Senior Agent",
  "permissions": [
    "ticket:read",
    "ticket:write",
    "call:read",
    "call:write",
    "recording:read",
    "report:read"
  ]
}

Team Management​

Create Team​

POST /api/v1/teams
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "name": "Premium Support",
  "description": "Handles premium customer accounts",
  "leader_id": "usr_supervisor123"
}

Add Users to Team​

POST /api/v1/teams/{team_id}/members
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "user_ids": ["usr_001", "usr_002", "usr_003"]
}

Permission Model​

Permissions follow the format resource:action:

user:read      - View users
user:write     - Create/update users
user:delete    - Delete users
user:*         - All user permissions

Common Permissions​

PermissionDescription
user:*Full user management
ticket:readView tickets
ticket:writeCreate/update tickets
call:*Full call operations
recording:readListen to recordings
report:*Access all reports

User Lifecycle​

Invite User​

POST /api/v1/users/invite
{
  "email": "newuser@example.com",
  "role": "agent"
}

Deactivate User​

PATCH /api/v1/users/{user_id}
{
  "status": "inactive"
}

Delete User​

DELETE /api/v1/users/{user_id}

Bulk Operations​

Import Users​

POST /api/v1/users/import
Content-Type: text/csv
Authorization: Bearer YOUR_TOKEN

email,name,role,team
user1@example.com,User One,agent,support
user2@example.com,User Two,agent,sales

Export Users​

GET /api/v1/users/export?format=csv

Security Settings​

Password Policy​

PATCH /api/v1/organization/security
{
  "password_policy": {
    "min_length": 12,
    "require_uppercase": true,
    "require_lowercase": true,
    "require_numbers": true,
    "require_symbols": true,
    "max_age_days": 90
  }
}

MFA Requirement​

PATCH /api/v1/organization/security
{
  "mfa_required": true,
  "mfa_methods": ["totp", "sms"]
}

Audit Logs​

Track user activity:

GET /api/v1/audit-logs?user_id=usr_123&action=login
{
  "logs": [
    {
      "id": "log_001",
      "user_id": "usr_123",
      "action": "user.login",
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0...",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ]
}