Skip to main content

Pivot user auths API

You can use the Pivot user auths API to create, read, and modify objects that represent user authentications.

After you create a user with the Pivot users API, you can send a POST request to the user auths API to set a password for the user.

Pivot must be running in native users mode.

Get all user auth objects​

Returns a list of all user auth objects.

URL​

GET /api/v1/user-auths

Success response​

CodeDescription
200"status": "ok"

Sample request​

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

Sample response​

{
    "userAuths": [
        {
            "name": "admin@example.com",
            "currentPass": {
                "createdAt": "2022-12-07T18:14:24.775Z",
                "pass": "$2a$12$PkK1S1P1BjW9IUKOftv",
                "hashStrategy": "bcrypt"
            },
            "passHistory": [
                {
                    "createdAt": "2022-12-07T18:14:24.775Z"
                }
            ]
        },
        {
            "name": "analyst@admin.com",
            "currentPass": {
                "pass": "my-password",
                "hashStrategy": "none"
            },
            "isTwoFactorAuthEnabled": false
        }
    ]
}

Get a user auth object​

Returns a user auth object for a user with a specified name. The name corresponds to the user ID in the Pivot UI.

URL​

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

Success response​

CodeDescription
200"status": "ok"

Sample error response​

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

Sample request​

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

Sample response​

{
    "userAuth": {
        "name": "admin@example.com",
        "currentPass": {
            "pass": "my-password",
            "hashStrategy": "none"
        },
        "isTwoFactorAuthEnabled": false
    }
}

Create a user auth object​

Creates a user auth object for a user with a specified name. The name corresponds to the user ID in the Pivot UI.

URL​

POST /api/v1/user-auths

Sample request​

curl -X POST 'http://PIVOT_URL/api/v1/user-auths' \
--header 'x-imply-api-token: <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "userAuth": {
    "name": "admin@example.com",
    "currentPass": {
        "hashStrategy":"none",
        "pass":"my-password"
        },
    "isTwoFactorAuthEnabled": false
  }
}'

Success response​

CodeDescription
200"status": "ok"

Sample error response​

CodeExample body
400 Bad Request"error": "name must be defined"

Sample response​

{
    "status": "ok",
    "message": "Created successfully",
    "userAuth": {
        "name": "admin@example.com",
        "currentPass": {
            "pass": "my-password",
            "hashStrategy": "none"
        },
        "isTwoFactorAuthEnabled": false
    }
}

Update a user auth object​

Updates the user auth object of a user with a specified name. The name corresponds to the user ID in the Pivot UI.

URL​

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

Sample request​

The following example request updates the hashStrategy and pass for the user with name admin@example.com. The name in the request body must match the {name} in the URL. You can't update the name field.

You must provide all properties you want to retain in the user auth object, even if you don't want to update them. Pivot recreates the object with the details you specify in the request.

curl -X POST 'http://PIVOT_URL/api/v1/user-auths/admin@example.com' \
--header 'x-imply-api-token: <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "userAuth": {
    "name": "admin@example.com",
    "currentPass": {
        "hashStrategy":"bcrypt",
        "pass":"$2a$12$PkK1S1P1BjW9IUKOftv"
        }
  }
}'

Success response​

CodeDescription
200"status": "ok"

Sample error response​

CodeExample body
400 Bad Request"error": "the name you entered does not match"

Sample response​

{
    "status": "ok",
    "message": "Updated successfully",
    "userAuth": {
        "name": "admin@example.com",
        "currentPass": {
            "pass": "$2a$12$PkK1S1P1BjW9IUKOftv",
            "hashStrategy": "bcrypt"
        }
    }
}

To update a user's status, send a POST request to the Pivot user statuses API.

Delete a user auth object​

Deletes a user auth object for a user with a specified name.

If you delete a user, you should also delete the corresponding user auth object and use the User status API to delete the corresponding user status.

URL​

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

Sample request​

curl -X DELETE 'http://PIVOT_URL/api/v1/user-auths/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 auth does not exist. Please check the name again."

Sample response​

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