Users API
- The
/users
API endpoint - The
/users/:user
API endpoint - The
/users/:user/password
API endpoint - The
/users/:user/reinstate
API endpoint - The
/users/:user/groups
API endpoint - The
/users/:user/groups/:group
API endpoints
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 |
|
output |
|
/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 |
|
payload parameters |
|
response codes |
|
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 |
|
output |
|
/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 |
|
response codes |
|
/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 |
|
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 |
|
payload parameters |
|
response codes |
|
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 |
|
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 |
|
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 |
|
/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 |
|