Users API

The /users API endpoint

/users (GET)

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 containing user definitions.

curl -H "Authorization: Bearer $SENSU_TOKEN" \
http://127.0.0.1:8080/api/core/v2/users

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. See the API overview for details.
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
  }
]

/users (POST)

The /users API endpoint provides HTTP POST access to create a user.

EXAMPLE

The following example demonstrates a POST request to the /users API to create the user alice, resulting in an HTTP 200 response and the created user definition.

curl -X POST \
-H "Authorization: Bearer $SENSU_TOKEN" \
-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 200 OK
{
  "username": "alice",
  "groups": [
    "ops"
  ],
  "disabled": false
}

API Specification

/users (POST)
description Create a Sensu user.
example URL http://hostname:8080/api/core/v2/users
payload 
{
  "username": "alice",
  "groups": [
    "ops"
  ],
  "password": "temporary",
  "disabled": false
}
payload parameters
  • username (string, required)
  • password (string, required): Must have at least eight characters
  • groups (array): Sets of shared permissions applicable to this user
  • disabled: When set to true, invalidates user credentials and permissions
response codes
  • Success: 200 (OK)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

The /users/:user API endpoint

/users/:user (GET)

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 containing the requested :user definition (in this example: for the alice user).

curl -H "Authorization: Bearer $SENSU_TOKEN" \
http://127.0.0.1:8080/api/core/v2/users/alice

HTTP/1.1 200 OK
{
  "username": "alice",
  "groups": [
    "ops"
  ],
  "disabled": false
}

API Specification

/users/:user (GET)
description Returns a user given the username as a URL parameter.
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
}

/users/:user (PUT)

EXAMPLE

The following example demonstrates a PUT request to the /users API to update the user alice, in this case to reset their password, resulting in an HTTP 200 response and the updated user definition.

curl -X PUT \
-H "Authorization: Bearer $SENSU_TOKEN" \
-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 200 OK
{
  "username": "alice",
  "groups": [
    "ops"
  ],
  "disabled": false
}

API Specification

/users/:user (PUT)
description Create or update a Sensu user given the username.
example URL http://hostname:8080/api/core/v2/users/alice
payload 
{
  "username": "alice",
  "groups": [
    "ops"
  ],
  "password": "reset-password",
  "disabled": false
}
response codes
  • Success: 200 (OK)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

/users/:user (DELETE)

EXAMPLE

In the following example, an HTTP DELETE request is submitted to the /users/:user API to disable the user alice, resulting in a successful 204 (No Content) HTTP response code.

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

HTTP/1.1 204 No Content

API Specification

/users/:user (DELETE)
description Disables a user given the username as a URL parameter.
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)

The /users/:user/password API endpoint

/users/:user/password (PUT)

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 to update the password for the user alice, resulting in a 200 (OK) HTTP response code.

curl -X PUT \
-H "Authorization: Bearer $SENSU_TOKEN" \
-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 200 OK

API Specification

/users/:user/password (PUT)
description Update the password for a Sensu user.
example URL http://hostname:8080/api/core/v2/users/alice/password
payload 
{
  "username": "admin",
  "password": "newpassword"
}
payload parameters
  • username (string, required): the username for the Sensu user
  • password (string, required): the user’s new password
response codes
  • Success: 200 (OK)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

The /users/:user/reinstate API endpoint

/users/:user/reinstate (PUT)

The /users/:user/reinstate API endpoint provides HTTP PUT access to re-enable a disabled user.

EXAMPLE

In the following example, an HTTP PUT request is submitted to the /users/:user/reinstate API to enable the disabled user alice, resulting in a 200 (OK) HTTP response code.

curl -X PUT \
-H "Authorization: Bearer $SENSU_TOKEN" \
-H 'Content-Type: application/json' \
http://127.0.0.1:8080/api/core/v2/users/alice/reinstate

HTTP/1.1 200 OK

API Specification

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

The /users/:user/groups API endpoint

/users/:user/groups (DELETE)

The /users/:user/groups API endpoint provides HTTP DELETE access to remove a user from all groups.

EXAMPLE

In the following example, an HTTP DELETE request is submitted to the /users/:user/groups API to remove the user alice from all groups within Sensu, resulting in a successful 204 (No Content) HTTP response code.

curl -X DELETE \
-H "Authorization: Bearer $SENSU_TOKEN" \
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 a 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)

The /users/:user/groups/:group API endpoints

/users/:user/groups/:group (PUT)

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 to add the user alice to the group ops, resulting in a successful 204 (No Content) HTTP response code.

curl -X PUT \
-H "Authorization: Bearer $SENSU_TOKEN" \
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 (PUT)
description Add a user to a group.
example URL http://hostname:8080/api/core/v2/users/alice/groups/ops
payload
response codes
  • Success: 204 (No Content)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

/users/:user/groups/:group (DELETE)

The /users/:user/groups/:group API endpoint provides HTTP DELETE access to remove a user from a group.

EXAMPLE

In the following example, an HTTP DELETE request is submitted to the /users/:user/groups/:group API to remove the user alice from the group ops, resulting in a successful 204 (No Content) HTTP response code.

curl -X DELETE \
-H "Authorization: Bearer $SENSU_TOKEN" \
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 a user from a 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)