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

Organization

Get Organization

GET /orgs/{organizationId}

Required Role: Any member (owner, admin, or chat)

Response: Returns the OrganizationSettings object. Bank-account details are omitted (use GET /orgs/{organizationId}/banking). Subscription fields are redacted for non-owners when the org’s billing visibility hides them.

Update Organization

PUT /orgs/{organizationId}

Required Role: Admin or Owner

Request Body: Partial update — send only the fields you want to change. Commonly edited fields:

{
  "name": "Acme Realty",
  "tradingName": "Acme",
  "abn": "12345678901",
  "email": "hello@acme.com",
  "phone": "+61400000000",
  "licence": "RE12345",
  "isRealEstate": true,
  "legalAddress": {},
  "tradingAddress": {}
}

Response: Returns the updated OrganizationSettings object.

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
• role (optional): Filter by role (owner, admin, or chat)

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 member (owner, admin, or chat)

Response: Returns OrganizationMemberWithUser object

Create User

POST /orgs/{organizationId}/users

Required Role: Admin or Owner

Required Fields:

• email: User email address
• name: User’s full name
• role: User role (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
• An invitation email is sent to new users

Update User Role

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

Required Role: Admin or Owner

Required Fields:

• role: New role for the user (admin or chat)

Request Body:

{
  "role": "admin"
}

Response: Returns updated OrganizationMember object

Restrictions:

• Cannot update your own role (403)
• role: "owner" is rejected with 400 — use the Owner Transfer flow instead

Delete User

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

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

Query Parameters:

• reassignWorkflowsTo (optional): User ID to reassign the removed member’s owned workflows to

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 what their members can reach. A group can be assigned specific agents, apps, app sites and site pages — or granted allow-all for any of those four families independently.

Full-access flags

A group stores four independent booleans, one per resource family:

fullAccess is not stored. It behaves differently on read and on write:

• On read it is computed: true only when all four granular flags are true, otherwise false. A group that is allow-all for three of the four families still reads fullAccess: false.
• On write it is a shorthand: sending fullAccess: true sets all four granular flags to true (and fullAccess: false clears all four). An explicit granular field in the same request body overrides the shorthand for that family only.

// Allow-all everywhere except site pages, in one request
{
  "fullAccess": true,
  "fullAccessAppSiteApps": false
}

Explicit grants (agent / app / app-site / site-page mappings) are still honoured for any family whose flag is false.

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
• q (optional): Search query for filtering groups

Response:

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

fullAccess is computed on read — it is false here because only fullAccessAgents is true.

Get User Group

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

Required Role: Admin or Owner

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: Write shorthand — sets all four granular flags at once (default: all four false)
• fullAccessAgents, fullAccessApps, fullAccessAppSites, fullAccessAppSiteApps: The granular flags. Any one passed here overrides the fullAccess shorthand for that family.

Request Body:

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

Response: Returns created UserGroup object — fullAccess on the response is the computed value, not the shorthand you sent.

Notes:

• Only one group can be the default group per organization
• Users not in any group automatically belong to the default group
• Omitted flags default to false, not to the shorthand’s absence

Update User Group

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

Required Role: Admin or Owner

Optional Fields (partial patch — send only what’s changing):

• name, description
• isDefault: true makes this the org’s default group
• fullAccess: Write shorthand — sets all four granular flags at once
• fullAccessAgents, fullAccessApps, fullAccessAppSites, fullAccessAppSiteApps

Request Body:

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

Response: Returns updated UserGroup object

Notes:

• Omitted fields keep their current values
• Setting isDefault: true automatically sets all other groups to isDefault: false. A group cannot be un-defaulted by sending isDefault: false — an org always has exactly one default group, so make another group the default instead
• A granular flag in the body wins over fullAccess in that same body, for its family only

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

List Group Members

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

Required Role: Admin or Owner

Lists every member of the group — users with an explicit assignment to it, plus (for the org’s default group) users who have no explicit group assignment at all. Sorted by name.

Response: An array of OrganizationMemberWithUser objects — the same shape GET /orgs/{organizationId}/users returns in its 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"
  }
]

Notes:

• Returns [] for a group nobody is assigned to
• Not paginated — the response is the full member list

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 fullAccessAgents: true
• Groups with fullAccessAgents: true already reach every agent

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 fullAccessAgents: 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 (the all-four shorthand) sparingly for admin/power user groups; prefer the granular flag for the one family a group actually needs

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; the granular flags for the tiers below it

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