Skip to content

API: Users & Authorities

This section covers user management, authenticated profile operations, and authority assignments.

Authorities Reference

Authority Description
MANAGE_USERS Manage users: change passwords, grant or remove authorities
MANAGE_LISTENERS Create, update, and delete listeners
MANAGE_PAYLOADS Create and delete payloads
MANAGE_AGENTS Manage agent state and metadata
MANAGE_DISCOVERY Edit and archive hosts, services, and credentials
SEND_COMMANDS Send commands to agents
MODIFY_FILES Upload, replace, and delete hosted files
VIEW_RESOURCES Base authority to view agents, listeners, files, and commands. Cannot be removed.
MANAGE_JOBS Pause, resume, and restart jobs

User API (v2)

The v2 API identifies users by stable GUID, returns permission metadata, and includes audit provenance. The examples below use bearer JWT authorization.

List users

1
2
GET /api/v2/users?page=0&pageSize=100&sort=ENABLED:DESC&sort=USERNAME:ASC HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

page is zero-based and defaults to 0. pageSize defaults to 100 and accepts values from 1 to 1000. Repeat sort to apply multiple criteria in order.

Supported sorting values are:

Field Accepted values
Username USERNAME, USERNAME:ASC, USERNAME:DESC
Enabled state ENABLED, ENABLED:ASC, ENABLED:DESC
Creation time CREATE_TIME, CREATE_TIME:ASC, CREATE_TIME:DESC
Update time UPDATE_TIME, UPDATE_TIME:ASC, UPDATE_TIME:DESC

The response uses the shared paged response fields, with eventful users in items.

Create a user

1
2
3
4
5
6
7
8
9
POST /api/v2/users HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "username": "{USER_NAME}",
  "password": "{USER_PASSWORD}",
  "authorities": ["VIEW_RESOURCES", "SEND_COMMANDS"]
}

username, password, and authorities are required. The username and password must each contain from 1 to 128 characters. authorities is an array of authority-code strings. A successful request returns the created eventful user.

Get my profile

1
2
GET /api/v2/users/me HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

The response is the eventful user for the authenticated account.

Change my password

1
2
3
4
5
6
7
8
PUT /api/v2/users/me/password HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "oldPassword": "{OLD_PASSWORD}",
  "newPassword": "{NEW_PASSWORD}"
}

Both fields are required and must contain at least one character. newPassword has a maximum length of 128 characters. A successful request returns 200 without a response body.

Get a user by GUID

1
2
GET /api/v2/users/{USER_GUID} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

USER_GUID must be a UUID. The response is the matching eventful user.

Update a user by GUID

1
2
3
4
5
6
7
8
PUT /api/v2/users/{USER_GUID} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "enabled": true,
  "authorities": ["VIEW_RESOURCES", "SEND_COMMANDS"]
}

authorities is required and contains authority-code strings. enabled is an optional nullable boolean. A successful request returns the updated eventful user.

Change a user's password by GUID

1
2
3
4
5
6
7
PUT /api/v2/users/{USER_GUID}/password HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "newPassword": "{NEW_PASSWORD}"
}

newPassword is required and must contain from 1 to 128 characters. A successful request returns 200 without a response body.

User response fields

Eventful user responses contain:

Field Type Description
userGuid UUID Stable user identifier
username string Login name
enabled boolean Whether the account is enabled
permissions array Unique permission metadata entries
createEvent object Creation audit metadata
lastUpdateEvent object Latest-update audit metadata

Each entry in permissions contains:

Field Type Description
label string Display label
code string Authority code used in requests
description string Permission description
mandatory boolean Whether the permission is mandatory

createEvent and lastUpdateEvent record the event UUID, type, time, and actor. See Eventful Responses and Audit Actors for the actor variants and their provenance fields.

Response outcomes

Operations Outcomes
List users; get my profile; change my password 200 success, 401 missing or wrong credentials, 403 insufficient privileges
Create a user 200 success, 401 missing or wrong credentials, 403 insufficient privileges, 409 username already exists
Get or update by GUID; change password by GUID 200 success, 401 missing or wrong credentials, 403 insufficient privileges, 404 user not found

v1 Compatibility API (Username-Based)

Existing integrations can continue to use the v1 endpoints. User-specific v1 paths identify accounts by username rather than GUID.

List available permissions

1
2
GET /api/v1/permissions HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

List all users

1
2
GET /api/v1/users HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Get user information

1
2
GET /api/v1/users/{USER_NAME} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Get my user information

1
2
GET /api/v1/users/me HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Change my password

1
2
3
4
5
6
7
8
PUT /api/v1/users/me/password HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "oldPassword": "{OLD_PASSWORD}",
  "newPassword": "{NEW_PASSWORD}"
}

Change a user's password

1
2
3
4
5
6
7
PUT /api/v1/users/{USER_NAME}/password HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "newPassword": "{NEW_PASSWORD}"
}

Add a user

1
2
3
4
5
6
7
8
9
POST /api/v1/users HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "username": "{USER_NAME}",
  "password": "{USER_PASSWORD}",
  "authorities": ["{AUTHORITY_1}", "{AUTHORITY_2}"]
}

Edit a user

1
2
3
4
5
6
7
8
PUT /api/v1/users/{USER_NAME} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "enabled": true,
  "authorities": ["{AUTHORITY_1}", "{AUTHORITY_2}"]
}