Users API

NOTE: The users API allows you to create and manage user credentials with Sensu’s built-in basic authentication provider. To configure user credentials with external provider like Lightweight Directory Access Protocol (LDAP), Active Directory (AD), or OpenID Connect 1.0 protocol (OIDC), use Sensu’s authentication providers API.

Get all users

The /users API endpoint provides HTTP GET access to user data.

Example

The following example demonstrates a request to the /users API, resulting in a JSON array that contains user definitions.

curl -X GET \
http://127.0.0.1:8080/api/core/v2/users \
-H "Authorization: Key $SENSU_API_KEY"

HTTP/1.1 200 OK
[
  {
    "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
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
output 
[
  {
    "username": "admin",
    "groups": [
      "cluster-admins"
    ],
    "disabled": false
  },
  {
    "username": "agent",
    "groups": [
      "system:agents"
    ],
    "disabled": false
  }
]

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, resulting in an HTTP 201 Created response and the created user definition.

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

HTTP/1.1 201 Created

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 
{
  "username": "alice",
  "groups": [
    "ops"
  ],
  "password": "temporary",
  "disabled": false
}
response codes
  • Success: 201 (Created)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

Get a specific user

The /users/:user API endpoint provides HTTP GET access to user data for a specific user by username.

Example

In the following example, querying the /users/:user API returns a JSON map that contains the requested :user definition (in this example, for the alice user).

curl -X GET \
http://127.0.0.1:8080/api/core/v2/users/alice \
-H "Authorization: Key $SENSU_API_KEY"

HTTP/1.1 200 OK
{
  "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
  • Success: 200 (OK)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)
output 
{
  "username": "alice",
  "groups": [
    "ops"
  ],
  "disabled": false
}

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), resulting in an HTTP 201 Created response.

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

HTTP/1.1 201 Created

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 
{
  "username": "alice",
  "groups": [
    "ops",
    "devel"
  ],
  "password": "password",
  "disabled": false
}
response codes
  • Success: 201 (Created)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

Delete 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 204 No Content response.

curl -X DELETE \
-H "Authorization: Key $SENSU_API_KEY" \
http://127.0.0.1:8080/api/core/v2/users/alice

HTTP/1.1 204 No Content

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
  • Success: 204 (No Content)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)

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, resulting in an HTTP 201 Created response.

The password_hash is the user’s new password, hashed via bcrypt. Use sensuctl user hash-password to generate the password_hash.

NOTE: Upgrade to Sensu 5.21.0 to use hashed passwords.

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

HTTP/1.1 201 Created

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:
  • username: string; the username for the Sensu user
  • password_hash: string; the new user password, hashed via bcrypt
payload 
{
  "username": "alice",
  "password_hash": "$5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm"
}
response codes
  • Success: 201 (Created)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

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, resulting in an HTTP 201 Created response.

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.

NOTE: Upgrade to Sensu 5.21.0 to use hashed passwords.

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

HTTP/1.1 201 Created

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:
  • username: string; the username for the Sensu user
  • password: string; the user’s current password in cleartext
  • password_hash: string; the user’s hashed password via bcrypt
payload 
{
  "username": "alice",
  "password": "P@ssw0rd!",
  "password_hash": "$5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm"
}
response codes
  • Success: 201 (Created)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

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, resulting in an HTTP 201 Created response.

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

HTTP/1.1 201 Created

API Specification

/users/:user/reinstate (PUT)
description Reinstates a disabled user.
example URL http://hostname:8080/api/core/v2/users/alice/reinstate
response codes
  • Success: 201 (Created)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

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 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

HTTP/1.1 204 No Content

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
  • Success: 204 (No Content)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)

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, resulting in a successful HTTP 201 Created response.

curl -X PUT \
-H "Authorization: Key $SENSU_API_KEY" \
http://127.0.0.1:8080/api/core/v2/users/alice/groups/ops

HTTP/1.1 201 Created

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
  • Success: 201 (Created)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

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 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

HTTP/1.1 204 No Content

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
  • Success: 204 (No Content)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)