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

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	`{ "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

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

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

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

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: `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.

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

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

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

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	Success: 200 (OK) Error: 500 (Internal Server Error)
output	`[ { "username": "alice", "groups": [ "ops", "dev" ], "disabled": false }, { "username": "balan", "groups": [ "testing", "dev" ], "disabled": false } ]`

core/v2/users

Get all users

Example

API Specification

Create a new user

Example

API Specification

Get a specific user

Example

API Specification

Create or update a user

Example

API Specification

Disable a user

Example

API Specification

Reset a user’s password

Example

API Specification

Change your password

Example

API Specification

Reinstate a disabled user

Example

API Specification

Remove a user from all groups

Example

API Specification

Assign a user to a group

Example

API Specification

Remove a user from a specific group

Example

API Specification

Get a subset of users with response filtering

Example

API Specification

Register your Sensu installation — Get rewards!

About Sensu

Navigation

Resources

Community

Get In Touch

Join Our Community