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 an external provider like Lightweight Directory Access Protocol (LDAP) or Active Directory (AD), 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.

Example

The following example demonstrates a PUT request to the /users API endpoint to update the user alice (in this case, to reset the user’s password), resulting in an HTTP 201 Created response and the updated user definition.

curl -X PUT \
-H "Authorization: Key $SENSU_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
  "username": "alice",
  "groups": [
    "ops"
  ],
  "password": "reset-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"
  ],
  "password": "reset-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)

Update a user password

The /users/:user/password API endpoint provides HTTP PUT access to update a user’s 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.

curl -X PUT \
-H "Authorization: Key $SENSU_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
  "username": "alice",
  "password": "newpassword"
}' \
http://127.0.0.1:8080/api/core/v2/users/alice/password

HTTP/1.1 201 Created

API Specification

/users/:user/password (PUT)
description Updates 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) and password (string; the user’s new password).
payload
{
  "username": "admin",
  "password": "newpassword"
}
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)