User Management

User Management

Manage organization members and user groups. Control access to agents through group-based permissions.

Overview

User management consists of:

1. Users - Organization members with assigned roles
2. User Groups - Collections of users with shared agent access permissions
3. Mappings - Relationships between users, groups, and agents

User Roles

• owner - Full access to organization, can manage all settings and users
• admin - Can manage users, agents, and resources (cannot manage owners)
• chat - Can only use agents they have access to

Users

List Users

GET /orgs/{organizationId}/users

Required Role: Admin or Owner

Query Parameters:

• limit (optional): Number of results (default: 100)
• cursor (optional): Pagination offset
• q (optional): Search query for filtering users

Response:

{
  "items": [
    {
      "organizationId": "org-123",
      "userId": "user-456",
      "role": "admin",
      "name": "John Doe",
      "email": "john@company.com",
      "sourceId": "auth0|123456",
      "userGroupId": "group-789",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "totalRows": 25,
  "offset": 0
}

Get User

GET /orgs/{organizationId}/users/{id}

Required Role: Any authenticated user

Response: Returns OrganizationMemberWithUser object

Create User

POST /orgs/{organizationId}/users

Required Role: Admin or Owner (only owners can create owners)

Required Fields:

• email: User email address
• name: User’s full name
• role: User role (owner, admin, or chat)

Request Body:

{
  "email": "jane@company.com",
  "name": "Jane Smith",
  "role": "admin",
}

Response: Returns created OrganizationMemberWithUser object

Notes:

• If user already exists in the system, they are added to the organization
• If user doesn’t exist, a new user account is created and invited
• Only owners can create new owners
• An invitation email is sent to new users

Update User Role

PUT /orgs/{organizationId}/users/{id}

Required Role: Admin or Owner (only owners can update owners)

Required Fields:

• role: New role for the user

Request Body:

{
  "role": "admin"
}

Response: Returns updated OrganizationMember object

Restrictions:

• Cannot update your own role
• Only owners can update the role of another owner
• Admins cannot update owners

Delete User

DELETE /orgs/{organizationId}/users/{id}

Required Role: Admin or Owner (only owners can delete owners)

Removes the user from the organization. Does not delete the user account.

Response:

{
  "message": "User membership deleted",
  "userId": "user-123"
}

Restrictions:

• Admins cannot delete owners
• Only owners can delete other owners

User Groups

User groups provide granular control over agent access. Groups can be assigned specific agents, or granted full access to all agents.

List User Groups

GET /orgs/{organizationId}/groups

Required Role: Admin or Owner

Query Parameters:

• limit (optional): Number of results (default: 20)
• cursor (optional): Pagination offset

Response:

{
  "items": [
    {
      "userGroupId": "group-123",
      "organizationId": "org-456",
      "name": "Sales Team",
      "description": "Sales representatives with access to sales tools",
      "isDefault": false,
      "fullAccess": false,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "totalRows": 5,
  "offset": 0
}

Get User Group

GET /orgs/{organizationId}/groups/{id}

Required Role: Any authenticated user

Response: Returns UserGroup object

Create User Group

POST /orgs/{organizationId}/groups

Required Role: Admin or Owner

Required Fields:

• name: Group name
• description: Group description

Optional Fields:

• isDefault: Whether this is the default group (default: false)
• fullAccess: Whether group has access to all agents (default: false)

Request Body:

{
  "name": "Engineering Team",
  "description": "Engineers with access to development tools",
  "isDefault": false,
  "fullAccess": false
}

Response: Returns created UserGroup object

Notes:

• Only one group can be the default group per organization
• Users not in any group automatically belong to the default group
• Groups with fullAccess: true can use all agents

Update User Group

PUT /orgs/{organizationId}/groups/{id}

Required Role: Admin or Owner

Required Fields:

• name: Group name
• description: Group description
• isDefault: Whether this is the default group
• fullAccess: Whether group has access to all agents

Request Body:

{
  "name": "Updated Engineering Team",
  "description": "Updated description",
  "isDefault": false,
  "fullAccess": true
}

Response: Returns updated UserGroup object

Notes:

• Setting isDefault: true automatically sets all other groups to isDefault: false
• All fields are required even if not changing

Delete User Group

DELETE /orgs/{organizationId}/groups/{id}

Required Role: Admin or Owner

Deletes the group and all its mappings (user assignments and agent assignments).

Response:

{
  "message": "User group deleted",
  "userGroupId": "group-123"
}

User Group Assignments

Assign User to Group

POST /orgs/{organizationId}/groups/{id}/users

Required Role: Admin or Owner

Required Fields:

• userId: User ID to assign to the group

Request Body:

{
  "userId": "user-123"
}

Response: Returns UserToGroupMapping object or undefined

Notes:

• Users can only be in one group at a time
• Assigning a user to a new group removes them from their previous group
• Users not in any group belong to the default group

Agent Access Control

List Group Agents

GET /orgs/{organizationId}/groups/{id}/agents

Required Role: Admin or Owner

Response:

[
  {
    "userGroupId": "group-123",
    "organizationId": "org-456",
    "agentId": "agent-789",
    "agentName": "Sales Assistant",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]

Grant Agent Access to Group

POST /orgs/{organizationId}/groups/{id}/agents

Required Role: Admin or Owner

Required Fields:

• agentId: Agent ID to grant access to

Request Body:

{
  "agentId": "agent-123"
}

Response: Returns UserGroupAgentMapping object

Notes:

• Only applies to groups without fullAccess: true
• Groups with full access already have access to all agents

Revoke Agent Access from Group

DELETE /orgs/{organizationId}/groups/{id}/agents/{agentId}

Required Role: Admin or Owner

Response:

{
  "message": "User group agent mapping deleted",
  "userGroupId": "group-123",
  "agentId": "agent-456"
}

Permission System

How Access Control Works

1. User Roles control what administrative actions users can perform
2. User Groups control which agents users can access
3. Agent Mappings define which agents each group can use

Access Hierarchy

Owner Role:

• Full access to everything
• Can manage all users including other owners
• Can access all agents

Admin Role:

• Can manage non-owner users
• Can manage agents and resources
• Agent access controlled by group membership

Chat Role:

• Cannot manage users or settings
• Agent access controlled by group membership only

Agent Access Logic

A user can access an agent if:

1. They are an owner (owners access all agents), OR
2. Their user group has fullAccess: true, OR
3. An agent mapping exists between their group and the agent

Default Group Behavior

• Only one group can be marked as isDefault: true
• Users not explicitly in a group belong to the default group
• The default group’s permissions apply to these users

Example Use Cases

Set Up Department-Based Access

1. Create groups for each department:

POST /orgs/org-123/groups
{
  "name": "Sales Department",
  "description": "Sales team members",
  "isDefault": false,
  "fullAccess": false
}

POST /orgs/org-123/groups
{
  "name": "Engineering Department",
  "description": "Engineering team members",
  "isDefault": false,
  "fullAccess": false
}

2. Grant each group access to relevant agents:

POST /orgs/org-123/groups/sales-group-id/agents
{
  "agentId": "sales-assistant-agent"
}

POST /orgs/org-123/groups/eng-group-id/agents
{
  "agentId": "code-review-agent"
}

3. Assign users to their departments:

POST /orgs/org-123/groups/sales-group-id/users
{
  "userId": "user-1"
}

POST /orgs/org-123/groups/eng-group-id/users
{
  "userId": "user-2"
}

Create Admin Users

POST /orgs/org-123/users
{
  "email": "admin@company.com",
  "name": "Admin User",
  "role": "admin"
}

Grant Full Access to Power Users

POST /orgs/org-123/groups
{
  "name": "Power Users",
  "description": "Users with access to all agents",
  "isDefault": false,
  "fullAccess": true
}

POST /orgs/org-123/groups/power-users-group-id/users
{
  "userId": "user-123"
}

Best Practices

1. Use Groups for Access Control - Don’t grant individual agent access; use groups
2. Default Group - Create a default group with minimal permissions for new users
3. Role Assignment - Use chat role for most users, admin for team leads, owner sparingly
4. Naming Convention - Use clear, descriptive names for groups (e.g., “Sales - West Region”)
5. Regular Audits - Periodically review user roles and group memberships
6. Least Privilege - Start with minimal permissions and add access as needed
7. Full Access Groups - Use fullAccess: true sparingly for admin/power user groups

Common Patterns

Multi-Tenant Setup

For organizations with multiple clients/teams:

1. Create separate user groups per client/team
2. Assign client-specific agents to each group
3. Users only see agents relevant to their client

Hierarchical Access

For tiered access levels:

1. Create groups: “Basic Users”, “Advanced Users”, “Power Users”
2. Grant increasing agent access at each level
3. Use fullAccess: true for the “Power Users” group

Temporary Access

For contractors or temporary access:

1. Create a dedicated group for contractors
2. Add contractor to the group
3. Remove from group when access no longer needed

Limitations

• One Group Per User: Users can only belong to one user group at a time
• One Default Group: Only one group can be marked as default per organization
• Owner Restrictions: Only owners can manage other owners
• Self-Management: Users cannot change their own role

Troubleshooting