core/v2/users
NOTE: The core/v2/users
API endpoints allow you to create and manage user credentials with Sensu’s built-in basic authentication.
To configure user credentials with an external provider like Lightweight Directory Access Protocol (LDAP), Active Directory (AD), or OpenID Connect 1.0 protocol (OIDC), use Sensu’s enterprise/authentication/v2 API endpoints.
Requests to core/v2/users
API endpoints require you to authenticate with a Sensu API key or access token.
The code examples in this document use the environment variable $SENSU_API_KEY
to represent a valid API key in API requests.
Get all users
The /users
API endpoint provides HTTP GET access to user data.
Example
The following example demonstrates a GET request to the /users
API:
curl -X GET \
http://127.0.0.1:8080/api/core/v2/users \
-H "Authorization: Key $SENSU_API_KEY"
The request results in a successful HTTP/1.1 200 OK
response and a JSON array that contains all user definitions:
[
{
"username": "admin",
"groups": [
"cluster-admins"
],
"disabled": false
},
{
"username": "agent",
"groups": [
"system:agents"
],
"disabled": false
}
]
API Specification
/users (GET) | |
---|---|
description | Returns the list of users. |
example url | http://hostname:8080/api/core/v2/users |
pagination | This endpoint supports pagination using the limit and continue query parameters. |
response filtering | This endpoint supports API response filtering. |
response type | Array |
response codes |
|
output |
|
Create a new user
The /users
API endpoint provides HTTP POST access to create a user using Sensu’s basic authentication provider.
Example
The following example demonstrates a POST request to the /users
API endpoint to create the user alice
:
curl -X POST \
-H "Authorization: Key $SENSU_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"username": "alice",
"groups": [
"ops"
],
"password": "temporary",
"disabled": false
}' \
http://127.0.0.1:8080/api/core/v2/users
The request will return a successful HTTP/1.1 201 Created
response.
API Specification
/users (POST) | |
---|---|
description | Creates a Sensu user. |
example URL | http://hostname:8080/api/core/v2/users |
payload parameters | Required: username (string), groups (array; sets of shared permissions that apply to this user), password (string; at least eight characters), and disabled (when set to true , invalidates user credentials and permissions). |
payload |
|
response codes |
|
Get a specific user
The /users/:user
API endpoint provides HTTP GET access to user data for a specific user by username
.
Example
The following example queries the /users/:user
API for the alice
user:
curl -X GET \
http://127.0.0.1:8080/api/core/v2/users/alice \
-H "Authorization: Key $SENSU_API_KEY"
The request will return a successful HTTP/1.1 200 OK
response and a JSON map that contains the requested :user
definition (in this example, alice
):
{
"username": "alice",
"groups": [
"ops"
],
"disabled": false
}
API Specification
/users/:user (GET) | |
---|---|
description | Returns the specified user. |
example url | http://hostname:8080/api/core/v2/users/alice |
response type | Map |
response codes |
|
output |
|
Create or update a user
The /users/:user
API endpoint provides HTTP PUT access to create or update user data for a specific user by username
.
NOTE: Use the PUT /users/:user/reset_password
or PUT /users/:user/password
API endpoints to reset or change the user password, respectively.
Example
The following example demonstrates a PUT request to the /users
API endpoint to update the user alice
(for example, to add the user to the devel
group):
curl -X PUT \
-H "Authorization: Key $SENSU_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"username": "alice",
"groups": [
"ops",
"devel"
],
"password": "password",
"disabled": false
}' \
http://127.0.0.1:8080/api/core/v2/users/alice
The request will return a successful HTTP/1.1 201 Created
response.
API Specification
/users/:user (PUT) | |
---|---|
description | Creates or updates user data for the specified Sensu user. |
example URL | http://hostname:8080/api/core/v2/users/alice |
payload |
|
response codes |
|
Disable a user
The /users/:user
API endpoint provides HTTP DELETE access to disable a specific user by username
.
Example
In the following example, an HTTP DELETE request is submitted to the /users/:user
API endpoint to disable the user alice
, resulting in a successful HTTP/1.1 204 No Content
response.
curl -X DELETE \
-H "Authorization: Key $SENSU_API_KEY" \
http://127.0.0.1:8080/api/core/v2/users/alice
NOTE: This endpoint disables but does not delete the user. You can reinstate disabled users.
API Specification
/users/:user (DELETE) | |
---|---|
description | Disables the specified user. |
example url | http://hostname:8080/api/core/v2/users/alice |
response codes |
|
Reset a user’s password
The /users/:user/reset_password
API endpoint provides HTTP PUT access to reset a user’s password.
NOTE: The /users/:user/reset_password
API endpoint requires explicit users
permissions.
With these permissions, you can use /users/:user/reset_password
to reset a user’s password.
This differs from the /users/:user/password
API endpoint, which allows users to change their own passwords without explicit permissions.
Example
In the following example, an HTTP PUT request is submitted to the /users/:user/reset_password
API endpoint to reset the password for the user alice
.
The password_hash
is the user’s new password, hashed via bcrypt.
Use sensuctl user hash-password
to generate the password_hash
.
curl -X PUT \
-H "Authorization: Key $SENSU_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"username": "alice",
"password_hash": "$5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm"
}' \
http://127.0.0.1:8080/api/core/v2/users/alice/reset_password
The request will return a successful HTTP/1.1 201 Created
response.
API Specification
/users/:user/reset_password (PUT) | |
---|---|
description | Resets the password for the specified Sensu user. |
example URL | http://hostname:8080/api/core/v2/users/alice/reset_password |
payload parameters | Required:
|
payload |
|
response codes |
|
Change your password
The /users/:user/password
API endpoint provides HTTP PUT access to change your Sensu user password.
NOTE: The /users/:user/password
API endpoint allows a user to update their own password, without any permissions.
This differs from the /users/:user/reset_password
API endpoint, which requires explicit users
permissions to change the user password.
Example
In the following example, an HTTP PUT request is submitted to the /users/:user/password
API endpoint to update the password for the user alice
.
The password
is your current password in cleartext.
The password_hash
is your new password hashed via bcrypt.
Use sensuctl user hash-password
to generate the password_hash
.
curl -X PUT \
-H "Authorization: Key $SENSU_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"username": "alice",
"password": "P@ssw0rd!",
"password_hash": "$5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm"
}' \
http://127.0.0.1:8080/api/core/v2/users/alice/password
The request will return a successful HTTP/1.1 201 Created
response.
API Specification
/users/:user/password (PUT) | |
---|---|
description | Changes the password for the specified Sensu user. |
example URL | http://hostname:8080/api/core/v2/users/alice/password |
payload parameters | Required:
|
payload |
|
response codes |
|
Reinstate a disabled user
The /users/:user/reinstate
API endpoint provides HTTP PUT access to reinstate a disabled user.
Example
In the following example, an HTTP PUT request is submitted to the /users/:user/reinstate
API endpoint to reinstate the disabled user alice
:
curl -X PUT \
-H "Authorization: Key $SENSU_API_KEY" \
-H 'Content-Type: application/json' \
http://127.0.0.1:8080/api/core/v2/users/alice/reinstate
The request will return a successful HTTP/1.1 201 Created
response.
API Specification
/users/:user/reinstate (PUT) | |
---|---|
description | Reinstates a disabled user. |
example URL | http://hostname:8080/api/core/v2/users/alice/reinstate |
response codes |
|
Remove a user from all groups
The /users/:user/groups
API endpoint provides HTTP DELETE access to remove the specified user from all groups.
Example
In the following example, an HTTP DELETE request is submitted to the /users/:user/groups
API endpoint to remove the user alice
from all groups within Sensu, resulting in a successful HTTP/1.1 204 No Content
response:
curl -X DELETE \
-H "Authorization: Key $SENSU_API_KEY" \
http://127.0.0.1:8080/api/core/v2/users/alice/groups
API Specification
/users/:user/groups (DELETE) | |
---|---|
description | Removes the specified user from all groups. |
example url | http://hostname:8080/api/core/v2/users/alice/groups |
response codes |
|
Assign a user to a group
The /users/:user/groups/:group
API endpoint provides HTTP PUT access to assign a user to a group.
Example
In the following example, an HTTP PUT request is submitted to the /users/:user/groups/:group
API endpoint to add the user alice
to the group ops
:
curl -X PUT \
-H "Authorization: Key $SENSU_API_KEY" \
http://127.0.0.1:8080/api/core/v2/users/alice/groups/ops
The request will return a successful HTTP/1.1 201 Created
response.
API Specification
/users/:user/groups/:group (PUT) | |
---|---|
description | Adds the specified user to the specified group. |
example URL | http://hostname:8080/api/core/v2/users/alice/groups/ops |
response codes |
|
Remove a user from a specific group
The /users/:user/groups/:group
API endpoint provides HTTP DELETE access to remove the specified user from a specific group.
Example
In the following example, an HTTP DELETE request is submitted to the /users/:user/groups/:group
API endpoint to remove the user alice
from the group ops
, resulting in a successful HTTP/1.1 204 No Content
response:
curl -X DELETE \
-H "Authorization: Key $SENSU_API_KEY" \
http://127.0.0.1:8080/api/core/v2/users/alice/groups/ops
API Specification
/users/:user/groups/:group (DELETE) | |
---|---|
description | Removes the specified user from the specified group. |
example url | http://hostname:8080/api/core/v2/users/alice/groups/ops |
response codes |
|
Get a subset of users with response filtering
The /users
API endpoint supports response filtering for a subset of user data based on labels and the following fields:
user.username
user.disabled
user.groups
Example
The following example demonstrates a request to the /users
API endpoint with response filtering for only user definitions whose user.groups include dev
:
curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/users -G \
--data-urlencode 'fieldSelector="dev" in user.groups'
The example request will result in a successful HTTP/1.1 200 OK
response and a JSON array that contains only user definitions whose user.groups include dev
:
[
{
"username": "alice",
"groups": [
"ops",
"dev"
],
"disabled": false
},
{
"username": "balan",
"groups": [
"testing",
"dev"
],
"disabled": false
}
]
NOTE: Read API response filtering for more filter statement examples that demonstrate how to filter responses using different operators with label and field selectors.
API Specification
/users (GET) with response filters | |
---|---|
description | Returns the list of users that match the response filters applied in the API request. |
example url | http://hostname:8080/api/core/v2/users |
pagination | This endpoint supports pagination using the limit and continue query parameters. |
response type | Array |
response codes |
|
output |
|