Skip to main content

Pivot user statuses API

You can use the Pivot user statuses API to create, read, and modify user statuses—for example, to set and remove the disabled status for a user.

Pivot must be running in native users mode.

Get all user statuses​

Returns a list of all user statuses.

URL​

GET /api/v1/user-statuses

Success response​

CodeDescription
200"status": "ok"

Sample request​

curl -X GET 'http://PIVOT_URL/api/v1/user-statuses' \
--header 'x-imply-api-token:<token>'

Sample response​

{
    "userStatuses": [
        {
            "name": "admin@example.com"
        },
        {
            "name": "analyst@example.com",
            "disabled": "2022-09-21T19:01:25.872Z"
        }
    ]
}

Get a user status​

Returns a user status with a specified name. The name corresponds to the user ID in the Pivot UI.

URL​

GET /api/v1/user-statuses/{name}

Success response​

CodeDescription
200"status": "ok"

Sample error response​

CodeExample body
404 Not Found"error": "This user status does not exist."

Sample request​

curl -X GET 'http://PIVOT_URL/api/v1/user-statuses/admin@example.com' \
--header 'x-imply-api-token:<token>'

Sample response​

{
    "userStatuses": [
        {
            "name": "admin@example.com",
            "disabled": "2022-09-21T19:01:25.872Z"
        }
    ]
}

Set a user status​

Sets the status of a user with a specified name. The name corresponds to the user ID in the Pivot UI.

URL​

POST /api/v1/user-statuses/{name}

If you send a POST request to /api/v1/user-statuses without {name} and include a new name in the request body, Pivot creates a user status entry for that name. There's no validation to check that the name is an existing user ID.

Sample request​

curl -X 'POST' \
  'http://PIVOT_URL/api/v1/user-statuses/admin@example.com' \
  -H 'x-imply-api-token: <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "userStatus": {
    "name": "admin@example.com",
    "disabled": "2022-07-21T19:01:25.872Z"
  }
}'

To re-enable a user, omit the "disabled" property from the message body. For example, the following sample request re-enables the admin@example.com user:

curl -X 'POST' \
  'http://PIVOT_URL/api/v1/user-statuses/admin@example.com' \
  -H 'x-imply-api-token: <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "userStatus": {
    "name": "admin@example.com"
  }
}'

Success response​

CodeDescription
200"status": "ok"

Sample error response​

CodeExample body
404 Not Found"error": "the name you entered does not match"

Sample response​

{
  "status":"ok",
  "message":"Updated successfully",
  "userStatus":
  {
    "name":"admin@example.com",
    "disabled":"2022-07-21T19:01:25.872Z"
  }
}

Delete a user status​

Deletes the status of a user with a specified name. If you use the Pivot users API to delete a user, you should also delete the corresponding user status. The name corresponds to the user ID in the Pivot UI.

Note that if you want to re-enable a disabled user, you should send a POST request to /user-statuses/{name} without the disabled property as shown in Set a user status.

URL​

DELETE /api/v1/user-statuses/{name}

Sample request​

curl -X DELETE 'http://PIVOT_URL/api/v1/user-statuses/admin@example.com' \
--header 'x-imply-api-token:<token>'

Success response​

CodeDescription
200"status": "ok"

Sample error response​

CodeExample body
404 Not Found"error": "This user status does not exist. Please check the name again"

Sample response​

{
    "status": "ok",
    "message": "Deleted successfully"
}