Users and Roles API

Use these endpoints to manage the people who can sign in to UTMStack v12 and what they are allowed to do: list, create, change and deactivate users, assign roles, build custom roles from the permission catalogue, and manage your own profile, password, sessions and two-step sign-in. Everything here works on every edition. On a multi-tenant installation, users and custom roles belong to the tenant of your credential.

Permissions

ActionPermissionBuilt-in roles that have it
List and read usersusers.readAdministrator, Analyst, Viewer
Create and change users, assign roles, reset another user's two-step sign-inusers.writeAdministrator
Deactivate usersusers.deleteAdministrator
List and read roles and the permission catalogueroles.readAdministrator, Analyst, Viewer
Create, change and delete custom rolesroles.writeAdministrator
Your own profile, password, sessions and two-step sign-in (/auth/..., /tfa/...)Any signed-in userAll

The three built-in roles (Administrator, Analyst and Viewer) are shared by every tenant and cannot be changed or deleted. See Roles and Permissions for what each role can do in the web console.

Users

User Object

FieldTypeDescription
idstring (UUID)User id
emailstringEmail address. This is also the sign-in name.
namestringDisplay name (left out when empty)
statusstringpending, active, inactive or suspended
lang_keystringInterface language of the user, for example en (left out when empty)
image_urlstringAddress of the profile picture (left out when there is none)
federatedbooleantrue when the account signs in through an identity provider (single sign-on or a directory)
tfa_enabledbooleantrue when the user has finished setting up two-step sign-in
rolesarrayRoles of the user, each with name and display_name
created_at, updated_atstringTimes in RFC 3339 format (single-user answers only)

Only active accounts can sign in or use their API keys.

StatusMeaning
pendingInvited, has not set a password yet
activeCan sign in
inactiveDeactivated. Cannot sign in; its API keys stop working and its sessions cannot be renewed.
suspendedCannot sign in

List Users

Endpoint: GET /api/v1/users (permission users.read)

Query Parameters:

ParameterTypeDescription
pageintegerPage number, starting at 1
page_sizeintegerDefault 20, maximum 200
searchstringPart of the email address or the name (upper and lower case ignored)

Users are sorted by creation time, oldest first.

curl -sk --get "{{baseUrl}}/api/v1/users" 
  -H "Utm-Api-Key: {{apiKey}}" 
  --data-urlencode "page=1" 
  --data-urlencode "page_size=50" 
  --data-urlencode "search=example.com"

Response (HTTP 200):

{
  "data": [
    {
      "id": "<user-id>",
      "email": "[email protected]",
      "name": "Dana Analyst",
      "status": "active",
      "lang_key": "en",
      "federated": false,
      "tfa_enabled": true,
      "roles": [
        {"name": "ROLE_ANALYST", "display_name": "Analyst"}
      ]
    }
  ],
  "page_info": {
    "page": 1,
    "page_size": 50,
    "total_items": 1,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

Ask for 200 users per page or fewer. In UTMStack v12.0.2 a larger page_size makes the server return 20 users, while page_info still shows the size you asked for.

Get One User

Endpoint: GET /api/v1/users/{id} (permission users.read)

curl -sk "{{baseUrl}}/api/v1/users/<user-id>" 
  -H "Utm-Api-Key: {{apiKey}}"

Response (HTTP 200): one user object, with created_at and updated_at. An unknown id returns 404 user not found; a value that is not a UUID returns 400 invalid id.

Create a User

Endpoint: POST /api/v1/users (permission users.write)

You can create the account in two ways:

  • With a password. The account is active at once and the user can sign in with the email address and that password. This is the reliable way to add a local user.

  • Without a password (invitation). The account is created as pending and UTMStack emails the user an invitation that is valid for 7 days. Email must be set up first (see Email Configuration). If the email cannot be sent, the account is still created and the error is only written to the server log.

Request Body:

FieldTypeRequiredDescription
emailstringYesA valid email address, unique in your tenant
namestringNoDisplay name
lang_keystringNoInterface language: en, es, pt, fr or de
role_namesarray of stringsNoRole names, for example ["ROLE_ANALYST"]. Every name must exist.
passwordstringNoInitial password. Leave it out to send an invitation instead.

Password rules (when you send a password): at least 8 characters, at least one upper-case letter, one lower-case letter and one special character (punctuation or symbol). Letters, digits, punctuation and symbols are allowed; spaces and other characters are refused.

curl -sk -X POST "{{baseUrl}}/api/v1/users" 
  -H "Utm-Api-Key: {{apiKey}}" 
  -H "Content-Type: application/json" 
  -d '{
    "email": "[email protected]",
    "name": "Dana Analyst",
    "lang_key": "en",
    "role_names": ["ROLE_ANALYST"],
    "password": "<initial-password>"
  }'

Response (HTTP 201): the new user object, including roles.

HTTP codeErrorCause
400password must have at least 8 characters (and similar password messages)The password breaks a rule above
400one or more role names do not existA name in role_names is unknown or repeated
400Validation messageemail missing or not an email address
409login or email already in useAnother user of the tenant has this email address

Update a User

Endpoint: PUT /api/v1/users/{id} (permission users.write)

Send only the fields you want to change. Empty or missing fields keep their value.

FieldTypeDescription
emailstringNew email address (must be unique in the tenant)
namestringNew display name
lang_keystringNew interface language
statusstringpending, active, inactive or suspended
curl -sk -X PUT "{{baseUrl}}/api/v1/users/<user-id>" 
  -H "Utm-Api-Key: {{apiKey}}" 
  -H "Content-Type: application/json" 
  -d '{"name": "Dana Senior Analyst", "status": "active"}'

Response (HTTP 200): the updated user object. An email address that is already in use returns 409 login or email already in use.

In UTMStack v12.0.2 the server does not check the status value. Send exactly one of the four values in the table.

To reactivate a deactivated user, send {"status": "active"}.

Deactivate a User

Endpoint: DELETE /api/v1/users/{id} (permission users.delete)

Sets the user's status to inactive. The account and its history are kept. The user can no longer sign in, renew a session or use an API key.

curl -sk -X DELETE "{{baseUrl}}/api/v1/users/<user-id>" 
  -H "Utm-Api-Key: {{apiKey}}"

Response: HTTP 204. An unknown id returns 404 user not found.

Assign Roles

Endpoint: PUT /api/v1/users/{id}/roles (permission users.write)

Replaces all roles of the user with the list you send. An empty list removes every role.

curl -sk -X PUT "{{baseUrl}}/api/v1/users/<user-id>/roles" 
  -H "Utm-Api-Key: {{apiKey}}" 
  -H "Content-Type: application/json" 
  -d '{"role_names": ["ROLE_ANALYST", "ROLE_SOC_LEAD"]}'

Response: HTTP 204.

HTTP codeErrorCause
400one or more role names do not existUnknown or repeated role name
403only an administrator can grant the administrator roleThe list contains ROLE_ADMIN and you do not hold the Administrator role
404user not foundUnknown user id

Reset a User's Two-Step Sign-In

Endpoint: POST /api/v1/users/{id}/tfa/disable (permission users.write)

Removes every two-step sign-in method of the user, for example after they lose their phone. They can set it up again after signing in.

curl -sk -X POST "{{baseUrl}}/api/v1/users/<user-id>/tfa/disable" 
  -H "Utm-Api-Key: {{apiKey}}"

Response: HTTP 204.

Roles

Role Object

FieldTypeDescription
idstring (UUID)Role id
namestringIdentifier used in role_names, for example ROLE_ANALYST
display_namestringName shown in the web console
descriptionstringFree text (left out when empty)
systembooleantrue for the three built-in roles, which cannot be changed or deleted
permissionsarraySingle-role answers only: each permission with name and description

List Roles

Endpoint: GET /api/v1/roles (permission roles.read)

Returns the built-in roles first, then your tenant's custom roles, sorted by name. There is no paging.

curl -sk "{{baseUrl}}/api/v1/roles" 
  -H "Utm-Api-Key: {{apiKey}}"

Response (HTTP 200):

[
  {
    "id": "00000000-0000-0000-0000-00000000a001",
    "name": "ROLE_ADMIN",
    "display_name": "Administrator",
    "description": "Full access, including users, roles and configuration",
    "system": true
  },
  {
    "id": "<role-id>",
    "name": "ROLE_SOC_LEAD",
    "display_name": "SOC lead",
    "system": false
  }
]

Get One Role

Endpoint: GET /api/v1/roles/{id} (permission roles.read)

Returns the role with its permissions. An unknown id returns 404 role not found; a value that is not a UUID returns 400 invalid role id.

List the Permission Catalogue

Endpoint: GET /api/v1/roles/permissions (permission roles.read)

curl -sk "{{baseUrl}}/api/v1/roles/permissions" 
  -H "Utm-Api-Key: {{apiKey}}"

Response (HTTP 200): an array of {"name": "...", "description": "..."}, sorted by name. UTMStack v12.0.2 has 42 permissions:

PermissionAllowsAdministratorAnalystViewer
users.readList and view usersYesYesYes
users.writeCreate and update users, and assign their rolesYes
users.deleteDeactivate usersYes
roles.readList and view roles and the permission catalogueYesYesYes
roles.writeCreate, update and delete the tenant's own rolesYes
idp.readList and view identity-provider configurationsYesYesYes
idp.writeCreate, update and delete identity-provider configurationsYes
tenant.readList and view tenantsYesYesYes
tenant.writeProvision, update and terminate tenantsYes
config.readRead application settingsYesYesYes
config.writeChange application settingsYes
audit.readList and view audit log entriesYesYesYes
notifications.readList and view notificationsYesYesYes
notifications.writeMark notifications read and delete themYesYes
alerts.readList and view alerts, tags and tag rulesYesYesYes
alerts.writeUpdate alerts and manage alert tags and tag rulesYesYes
incidents.readList and view incidents, their alerts, notes and historyYesYesYes
incidents.writeCreate and manage incidents, their alerts and notesYesYes
soar.readList and view response flowsYesYesYes
soar.writeCreate response flows and run console commandsYesYes
soar.executeStart response flows by handYes
compliance.readList and view frameworks, controls, reports and score historyYesYesYes
compliance.writeManage frameworks and controls, run evaluations, record verdicts and manage report schedulesYes
dashboards.readList and view dashboards and visualizationsYesYesYes
dashboards.writeCreate, update and delete dashboards and visualizationsYesYes
loganalyzer.readSearch logs and view saved queriesYesYesYes
loganalyzer.writeCreate, update and delete saved queriesYesYes
datasources.readList and view data sourcesYesYesYes
datasources.writeChange data source labels and sensitivity, delete data sourcesYes
eventprocessing.readList and view correlation rules, pipelines and patternsYesYesYes
eventprocessing.writeChange correlation rules and pipelines, run the test playgroundYes
integrations.readList integrations and their configurationYesYesYes
integrations.writeActivate integrations and manage their configurationYes
adaudit.readView the audited user inventory (User Auditor)YesYesYes
adaudit.writeCreate and manage identity aliases in the User AuditorYes
threatintel.readSearch threat intelligence and its feedsYesYesYes
storage.readRead retention and storage useYesYesYes
storage.writeChange retention and configure cold storageYes
socai.readUse the SOC-AI assistantYesYesYes
socai.writeConfigure the SOC-AI providerYes
apikey.readList your own API keysYesYesYes
apikey.writeCreate and manage your own API keysYes

Some endpoints also need a role or a licence on top of the permission. For example, tenant management needs the multi-tenant licence and the Administrator role in the default tenant, so tenant.read alone does not let an Analyst list tenants. Each API page names these extra conditions.

Create a Custom Role

Endpoint: POST /api/v1/roles (permission roles.write)

FieldTypeRequiredDescription
namestringYesIdentifier, 2 to 50 characters, unique in your tenant. The web console suggests the prefix ROLE_.
display_namestringNoName shown in the web console
descriptionstringNoFree text
permissionsarray of stringsNoPermission names from the catalogue. An empty list creates a role with no permissions.
curl -sk -X POST "{{baseUrl}}/api/v1/roles" 
  -H "Utm-Api-Key: {{apiKey}}" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "ROLE_SOC_LEAD",
    "display_name": "SOC lead",
    "description": "Analyst who can also start flows by hand",
    "permissions": ["alerts.read", "alerts.write", "incidents.read", "incidents.write",
                    "loganalyzer.read", "soar.read", "soar.write", "soar.execute"]
  }'

Response (HTTP 201): the new role with its permissions.

HTTP codeErrorCause
400role name is already in useA built-in or custom role already has this name
400permission not foundA name in permissions is not in the catalogue
400Validation messagename missing, shorter than 2 or longer than 50 characters

Update a Custom Role

Endpoint: PUT /api/v1/roles/{id} (permission roles.write)

Takes the same body as create and replaces the whole role: name, display name, description and the full permission list. API keys of users who hold the role get the new permissions at once; signed-in users get them the next time they sign in or renew their token.

Response (HTTP 200): the updated role. A built-in role returns 403 system roles cannot be modified.

Delete a Custom Role

Endpoint: DELETE /api/v1/roles/{id} (permission roles.write)

Response: HTTP 204. The role is also removed from every user who held it. A built-in role returns 403 system roles cannot be modified; an unknown id returns 404 role not found.

Your Own Account

These endpoints act on the user who owns the credential. Signing in, renewing tokens and the current-user call (GET /auth/me) are on Authentication and API Keys.

Update Your Profile

Endpoint: PUT /api/v1/auth/me

FieldTypeDescription
emailstringNew email address (also your sign-in name)
namestringDisplay name
lang_keystringInterface language: en, es, pt, fr or de

Empty or missing fields keep their value.

curl -sk -X PUT "{{baseUrl}}/api/v1/auth/me" 
  -H "Authorization: Bearer <access-token>" 
  -H "Content-Type: application/json" 
  -d '{"name": "Dana Analyst", "lang_key": "es"}'

Response (HTTP 200): your user object (without roles). An email address used by someone else returns 409 email is already in use.

GET /api/v1/auth/authenticate returns only your email address as plain text. It is a quick way to check that a credential works.

Upload or Remove Your Profile Picture

Endpoint: POST /api/v1/auth/me/avatar (multipart form, field file)

The image must be PNG, JPEG, WebP or GIF and at most 2 MB. The server checks the file content, not the file name.

curl -sk -X POST "{{baseUrl}}/api/v1/auth/me/avatar" 
  -H "Authorization: Bearer <access-token>" 
  -F "[email protected]"

Response (HTTP 200): your user object with the new image_url, for example /uploads/avatars/u<user-id>-<random>.png?v=<time>.

HTTP codeError
400missing file field
413image is too large (max 2MB)
415only png/jpeg/webp/gif images are allowed

DELETE /api/v1/auth/me/avatar removes the picture and returns your user object.

Change Your Password

Endpoint: POST /api/v1/auth/change-password

FieldTypeRequiredDescription
current_passwordstringYesYour current password
new_passwordstringYesAt least 8 characters, different from the current one
curl -sk -X POST "{{baseUrl}}/api/v1/auth/change-password" 
  -H "Authorization: Bearer <access-token>" 
  -H "Content-Type: application/json" 
  -d '{"current_password": "<current-password>", "new_password": "<new-password>"}'

Response: HTTP 204. Every session of your account, including the one you are using, can no longer be renewed: sign in again when your access token expires.

HTTP codeErrorCause
400new password must differ from currentSame password sent twice
400Validation messageA field is missing or the new password is shorter than 8 characters
401current password is incorrectWrong current password
500could not change passwordAlso returned in UTMStack v12.0.2 for accounts that sign in through an identity provider, which have no UTMStack password

List and Revoke Your Sessions

A session is one sign-in that can still be renewed. Each one keeps the address and browser it came from. A session that is not renewed for 30 days expires (expires_at).

Endpoint: GET /api/v1/auth/sessions

curl -sk "{{baseUrl}}/api/v1/auth/sessions" 
  -H "Authorization: Bearer <access-token>"

Response (HTTP 200):

[
  {
    "id": "<session-id>",
    "ip": "192.0.2.25",
    "user_agent": "Mozilla/5.0 ...",
    "created_at": "2026-11-10T08:02:11Z",
    "expires_at": "2026-12-10T08:02:11Z",
    "current": true
  }
]

current is true for the session of the token you are calling with. With an API key no session is marked as current.

MethodEndpointResult
DELETE/api/v1/auth/sessions/{id}Revokes one session so it cannot be renewed. HTTP 204, or 404 session not found.
DELETE/api/v1/auth/sessionsRevokes every session except the one you are calling from. HTTP 204. Needs a bearer token: with an API key the answer is 400 no active session to preserve.

Set Up Two-Step Sign-In

Two-step sign-in asks for a 6-digit code after the password. The code comes from an authenticator app (totp) or by email (email). Set-up has three stages, all sent to the same endpoint.

Endpoint: POST /api/v1/tfa/enroll

FieldTypeRequiredDescription
stagestringYesINIT, VERIFY or COMPLETE
typestringYestotp or email
codestringFor VERIFYThe 6-digit code
  1. 1

    Start (INIT)

    curl -sk -X POST "{{baseUrl}}/api/v1/tfa/enroll" 
      -H "Authorization: Bearer <access-token>" 
      -H "Content-Type: application/json" 
      -d '{"stage": "INIT", "type": "totp"}'

    For totp the answer contains qr_data_url (a PNG image of the QR code) and otp_auth_url (the same secret as an otpauth:// link). Add it to your authenticator app. For email a code is sent to your address and the answer has "email_sent": true; the code is valid for 10 minutes.

    {
      "stage": "INIT",
      "init": {
        "type": "totp",
        "factor_id": "<factor-id>",
        "qr_data_url": "data:image/png;base64,...",
        "otp_auth_url": "otpauth://totp/...",
        "expires_at": "2026-11-10T08:12:11Z"
      }
    }
  2. 2

    Confirm the code (VERIFY)

    curl -sk -X POST "{{baseUrl}}/api/v1/tfa/enroll" 
      -H "Authorization: Bearer <access-token>" 
      -H "Content-Type: application/json" 
      -d '{"stage": "VERIFY", "type": "totp", "code": "123456"}'

    The answer is {"stage": "VERIFY", "verified": true}. From now on, sign-in asks for a code.

  3. 3

    Check (COMPLETE)

    Send {"stage": "COMPLETE", "type": "totp"}. The answer {"stage": "COMPLETE", "enabled": true} confirms that two-step sign-in is on for your account.

HTTP codeErrorCause
400a tfa factor of this type is already enrolledYou already finished set-up for this type
401invalid tfa codeWrong or old code
404tfa factor not found, challenge has expiredVERIFY without INIT, or the email code is older than 10 minutes
503the second factor is sent by email, and no mail server is configuredEmail is not set up (see Email Configuration)

To finish a sign-in with a code, use POST /api/v1/auth/tfa/verify-code (see Authentication and API Keys).

Turn Off Two-Step Sign-In

Endpoint: POST /api/v1/tfa/disable

curl -sk -X POST "{{baseUrl}}/api/v1/tfa/disable" 
  -H "Authorization: Bearer <access-token>" 
  -H "Content-Type: application/json" 
  -d '{"password": "<your-password>"}'

Response: HTTP 204. A wrong password returns 400 current password is incorrect. Accounts that sign in through an identity provider have no UTMStack password; ask an administrator to reset two-step sign-in for them instead (POST /users/{id}/tfa/disable).

Password Reset by Email

Two endpoints need no credential:

  • POST /api/v1/auth/reset-password/init with {"email": "[email protected]"} always answers HTTP 204, whether or not the account exists. For an active local account, UTMStack emails a reset key that is valid for 1 hour.

  • POST /api/v1/auth/reset-password/finish with {"key": "<reset-key>", "new_password": "<new-password>"} sets the password (at least 8 characters) and answers HTTP 204. An unknown or expired key returns 410 invalid or expired reset key. All sessions of the account must sign in again.

Accounts that sign in through an identity provider cannot reset a password here.

Paging

EndpointPage parameterFirst pageSize parameterDefaultLargestTotal
GET /userspage1page_size20200page_info in the answer
GET /roles, /roles/permissions, /auth/sessionsNo paging