Managing users and groups by using the REST API
You can manage users and groups by using the /security/users endpoint. The equivalent manual procedure is described in Managing-system-users and Managing-groups.
To manage users
Get a list of defined users
To retrieve the current configuration, use the GET /security/users endpoint.
The endpoint returns JSON formatted data listing the users defined:
{
"username": "api_user",
"fullname": "api_user",
"state": "ACTIVE",
"groups": [
"admin",
"api-access",
"never-deactivate",
"system"
],
"password_state": "NOT_PERMITTED",
"last_login_time": "1970-01-01T00:59:59",
"last_pw_change": "1970-01-01T00:59:59"
},
{
"username": "system",
"fullname": "System User",
"state": "ACTIVE",
"groups": [
"public",
"system"
],
"password_state": "OK",
"last_login_time": "2024-08-15T15:23:19",
"last_pw_change": "2024-08-13T14:45:00"
}
]
The endpoint return code is: 200 successful operation
Add a user
Use the POST /security/users endpoint to create a new user. Define the user with JSON of the following form:
"username": "another_api_user",
"fullname": "api_q_user",
"state": "ACTIVE",
"groups": [
"admin",
"api-access",
"never-deactivate",
"system"
]
}
- type—the default is user
- password—the password is entered and sent in clear text
- groups—the groups to which the new user belongs
The endpoint return codes are:
- 201 created
- 400 missing or invalid parameters
Get and modify a user's details
To retrieve the current configuration, use the GET /security/users/{name} endpoint.
The endpoint returns JSON formatted data listing the details for the user. For example, retrieving the user called modeler:
"username": "modeler",
"fullname": "Service and application modeler",
"state": "ACTIVE",
"groups": [
"public",
"appmodel"
],
"password_state": "OK",
"last_login_time": "2024-08-16T09:26:16",
"last_pw_change": "2024-08-16T02:37:57"
}
Modify the user's details; in this case, we are adding the discovery permission:
"username": "modeler",
"fullname": "Service and application modeler",
"state": "ACTIVE",
"groups": [
"public",
"appmodel",
"discovery"
]
}
Use the PATCH /security/users/{name} endpoint to update a user's details.
The endpoint return codes are:
- 200 successful operation
- 400 Missing or invalid parameters
- 404 Group does not exist
To obtain a token for an API user
To retrieve the current configuration, use the GET /security/users/{name}/token endpoint. You can only generate new security token only for users who do not have permissions for a local login.
For example, for a newly created API user called new_api_user, use:
GET /security/users/new_api_user/token
The endpoint returns the token as a JSON formatted string.
The endpoint return codes are:
- 200 OK
- 400 Cannot get token for non API user
- 404 User does not exist
To delete a user
Use the DELETE /security/users/{name} endpoint to delete a user.
The endpoint return codes are:
- 204 successful delete
- 400 Error deleting user
- 404 User does not exist
To manage groups
Get a list of defined groups
To retrieve the current configuration, use the GET /security/groups endpoint.
The endpoint returns JSON formatted data with a list of the groups defined:
{
"name": "maintenance",
"permissions": [
"appliance/maintenance"
]
},
...
{
"name": "event-source",
"permissions": [
"api/access",
"api/event_source"
]
}
The endpoint return code is: Successful operation
Add a group
Use the POST /security/groups endpoint to create a new group. Define the group with JSON of the following form:
"name": "the group",
"permissions": [
"permission_1",
"permission_2"
]
}
The endpoint return codes are:
- 201 Created
- 400 Missing or invalid parameters
Get and modify a group's details
Use the GET /security/groups/{name} endpoint to the current configuration of a named group..
The endpoint returns JSON formatted data listing the details for the group. In this example, the cmdb-export-administrator group:
"name": "cmdb-export-administrator",
"permissions": [
"cmdb_sync",
"vault/close",
"vault/open"
]
}
Use the PATCH /security/groups/{name} endpoint to update a named group's details.
The endpoint return codes are:
- 200 Successful operation
- 400 Missing or invalid parameters
- 404 Group does not exist
To delete a group
Use the DELETE /security/groups/{name} endpoint to delete a named group.
The endpoint return codes are:
- 204 Successful delete
- 400 Error deleting group
- 404 Group does not exist