Pivot users API

Create, read, or edit your users using the Pivot API.

Pivot must be running in native users mode.

Get all users or a get single named user

Returns a list of all user, or returns a user with a {name} that you specify.

URL

GET /api/v1/users/{name}

Success response

Code	Description
200	OK

Selected error response

Code	Example body
404 Not Found	”error": "Not found."

Sample request

curl --location --request GET 'http://localhost:9095/api/v1/users' \
--header 'x-imply-api-token:<token>'

Response body

[
  {
    "name": "string",
    "firstName": "string",
    "lastName": "string",
    "colorMode": "string",
    "users": [
      "string"
    ]
  }
]

Create or update a user by name

Creates or updates a user with a {name} that you specify.

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

When creating a user, you can add "sendWelcomeEmail": true to the body of the request to have a welcome email sent to the new user with a password change prompt.

The default template for the welcome email is in the Pivot configuration file:

emailTemplates:
  - name: invite
    subject: Create your pivot account
    html: 'Please use this link to set your password: ${linkProtocol}://${linkHost}${linkPath}'

To specify a custom invite email template, provide an entry in the emailTemplates block with name invite.

By default, if you set sendWelcomeEmail to true, the Host HTTP header populates the ${linkHost}${linkPath} in the link sent to your new users. You can override this default URL by setting clientUrl to the URL you want to use. You can use clientUrl when the request hostname differs from the URL you want to use, such as when there are load balancers serving your request.

URL

POST /api/v1/users/{name}

Request body

curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "user": {
    "name": "string",
    "firstName": "string",
    "lastName": "string",
    "colorMode": "string",
    "users": [
      "string"
    ]
  }
}

Success response

Code	Description
200	OK

Selected error response

Code	Example body
404 Not Found	”error": "Not found."

Response body

[
  {
    "name": "string",
    "firstName": "string",
    "lastName": "string",
    "colorMode": "string",
    "users": [
      "string"
    ]
  }
]

Delete a user by name

Deletes a user with a {name} that you specify. If you delete a user, you should also use the User status API to delete the corresponding user status.

URL

DELETE /api/v1/users/{name}

Sample request

curl -X DELETE --header "x-imply-api-token:<token>" localhost:9095/api/v1/users/<userName>

Success response

Code	Description
200	OK

Selected error response

Code	Example body
404 Not Found	”error": "Not found."