User Management API

Automate user role management and team membership

The User Management API (released with 5.27.0) allows automation of user role management and team membership.

OpenAPI Reference

Invite user by email

POST

Invite a user to join a team with a specific role.

Behavior:

• If the user already exists in the organization, they will be immediately added to the team
• If the user doesn't exist, an invitation email will be sent

Role Assignment Permissions:

• Admin can invite users with any role (Member, TeamLead, Manager, Admin)
• Manager can invite users with Member, TeamLead, or Manager roles (cannot invite Admin)

Restrictions:

• Cannot invite users to teams that have been synced from external groups
• Team must belong to the same organization as the inviter

Authorizations

BearerAuth

AuthorizationstringRequired

JWT ID Token obtained from authentication endpoints.

Required Roles:

• POST /invitation/v1: Admin or Manager
• PATCH /user/v1/:userId: Admin or Manager

Include in the Authorization header as: Bearer {token}

Body

application/json

emailstring · emailRequired

Email address of the user to invite

Example: [email protected]

teamIdstring · uuidRequired

UUID of the team to invite the user to

Example: 123e4567-e89b-12d3-a456-426614174000

rolestring · enumRequired

Role to assign to the user.

• Admin can assign any role
• Manager can assign Member, TeamLead, Manager (not Admin)

Example: MemberPossible values:

Responses

200

Existing user successfully added to team

application/json

successbooleanRequiredExample: true

messagestringRequiredExample: Existing user successfully added to team

userExistsbooleanRequired

Indicates the user already existed in the organization

Example: true

userIdstring · uuidRequired

UUID of the existing user

Example: 987e6543-e21b-12d3-a456-426614174999

201

Invitation email sent successfully to new user

application/json

400

Bad request - Invalid input or team constraints

application/json

401

Unauthorized - Missing or invalid authentication token

application/json

403

Insufficient permissions to assign role

application/json

404

Team not found

application/json

500

Internal server error

application/json

POST

/invitation/v1

HTTPcURLJavaScriptPython

POST /api/invitation/v1 HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 95

{
  "email": "[email protected]",
  "teamId": "123e4567-e89b-12d3-a456-426614174000",
  "role": "Member"
}

{
  "success": true,
  "message": "Existing user successfully added to team",
  "userExists": true,
  "userId": "987e6543-e21b-12d3-a456-426614174999"
}

Update user

PATCH

Update user properties including role, activation status, and team assignment.

Available Updates:

• role: Change the user's role in the organization
• active: Activate or deactivate the user
• teamId: Assign user to a team (or remove from team with null)

Role Update Permissions:

• Acting user must have sufficient permissions to modify the target user's current role
• Acting user must have sufficient permissions to assign the new role
• Admin can assign any role
• Manager can assign Member, TeamLead, or Manager roles (cannot assign Admin)

Restrictions:

• Cannot modify own account
• Cannot modify anonymized users
• Cannot modify instance administrators
• Cannot activate/deactivate or change team assignment for synced users

All fields are optional - provide only the fields you want to update.

Authorizations

BearerAuth

AuthorizationstringRequired

JWT ID Token obtained from authentication endpoints.

Required Roles:

• POST /invitation/v1: Admin or Manager
• PATCH /user/v1/:userId: Admin or Manager

Include in the Authorization header as: Bearer {token}

Path parameters

userIdstring · uuidRequired

The unique identifier of the user to update

Example: 987e6543-e21b-12d3-a456-426614174999

Body

application/json

All fields are optional. Provide only the fields you want to update.

rolestring · enumOptional

New role to assign to the user. Acting user must have sufficient permissions to assign this role.

Example: ManagerPossible values:

activebooleanOptional

Activation status of the user. Cannot be modified for synced users.

Example: true

teamIdstring · uuid · nullableOptional

UUID of the team to assign the user to. Set to null to remove the user from their current team. Cannot be modified for synced users.

Example: 456e7890-e89b-12d3-a456-426614174111

Responses

200

User updated successfully

application/json

successbooleanRequiredExample: true

messagestringRequiredExample: User updated successfully

400

Bad request - Invalid input

application/json

401

Unauthorized - Missing or invalid authentication token

application/json

403

Forbidden - Insufficient permissions or unauthorized action

application/json

404

User or team not found

application/json

409

Conflict - User state prevents modification

application/json

422

Unprocessable Entity - Insufficient permissions for role operation

application/json

500

Internal server error

application/json

PATCH

/user/v1/{userId}

HTTPcURLJavaScriptPython

PATCH /api/user/v1/{userId} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "role": "Manager"
}

{
  "success": true,
  "message": "User updated successfully"
}

Permissions

Role	Assign Team	Update Role	Activate/Deactivate	Invite
Admin	✓	✓ (all roles)	✓	✓ (all roles)
Manager	✓	✓ (Member, Team Lead, Manager)	✓	✓ (Member, Team Lead, Manager)
Team Lead	✗	✗	✗	✗
Member	✗	✗	✗	✗

To use this API, you will need user and team data, which you can retrieve via current currently implemented Organization & Team APIs.