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