Users endpoints

With role-based access control (RBAC), you can manage local users and remote users (created on a directory service). Use the RBAC API v2 GET /users endpoint to get lists of users and information about users.

Use the RBAC API v1 Users endpoints for other user functions, including creating, editing, deleting, revoking, and reinstating users.

Users endpoints keys

These keys appear in RBAC API v2 GET /users endpoint responses:


Key	Definition	Example
`id`	A UUID string identifying the user.	`"4fee7450-54c7-11e4-916c-0800200c9a66"`
`login`	A string used by the user to log in. Must be unique among users and groups.	`"admin"`
`email`	An email address string. Not currently utilized by any code in PE.	`"hill@example.com"`
`display_name`	The user's name as a string.	`"Kalo Hill"`
`role_ids`	An array of role IDs indicating roles to directly assign to the user. An empty array is valid.	`[3 6 5]`
`is_group` `is_remote` `is_superuser`	These flags indicate whether a user is remote and/or a super user. For all users, `is_group` is always `false`.	`true`/`false`
`is_revoked`	Setting this flag to `true` prevents the user from accessing any routes until the flag is unset or the user's password is reset via token.	`true`/`false`
`last_login`	A timestamp in UTC-based ISO-8601 format (`YYYY-MM-DDThh:mm:ssZ`) indicating when the user last logged in. If the user has never logged in, this value is null.	`"2014-05-04T02:32:00Z"`
`inherited_role_ids` (remote users only)	An array of role IDs indicating which roles a remote user inherits from their groups.	`[9 1 3]`
`group_ids` (remote users only)	An array of UUIDs indicating which groups a remote user inherits roles from.	`["3a96d280-54c9-11e4-916c-0800200c9a66"]`

GET /users

Fetches all users, both local and remote (including the superuser) with options for filtering and sorting response content. Authentication is required.

Request format

When Forming RBAC API requests to this endpoint, the request is a basic call with authentication, such as:

curl "https://$(puppet config print server):4433/rbac-api/v2/users" -H "X-Authentication:$(puppet-access show)"

The default request fetches all users (limited to 500 records, sorted by subject ID in ascending order). You can append these optional query parameters to modify the response:

offset: Specify a zero-indexed integer to retrieve user records starting from the offset point. The default is 0. This parameter is useful for omitting initial, irrelevant results, such as test data.
limit: Specify a positive integer to limit the number of user records returned. The default is 500 records.
order: Specify, as a string, whether records are returned in ascending (asc) or descending (desc) order. The default is asc. The order_by parameter specifies the basis for sorting.
order_by: Specify, as a string, what information to use to sort the records. Choose from login, email, display_name, last_login, id, or creation_date. The default is id.
filter: Specify a case-insensitive partial string. This parameter queries the email, display_name, and login fields. For example, filter="example.com" searches for users with example.com in any of those three fields.
include_roles: Specify whether you want the response to include role information. The default is false.

To include parameters in your request, start with:

curl "https://$(puppet config print server):4433/rbac-api/v2/users?"

Then, add each parameter separated by an ampersand, such as:

limit=400&order="desc"

Enclose string values in double quotes. To form a complete request, make sure to close the single quote after your last parameter and include authentication details. For example:

curl "https://$(puppet config print server):4433/rbac-api/v2/users?limit=400&offset=1&order="desc"&order_by="last_login"&filter="example.com"&include_roles=true" \
-H "X-Authentication:$(puppet-access show)"

Response format

The response is a JSON array of user objects followed by a copy of the request parameters. User objects contain role information only if you put include_roles=true in the request. For example, this response includes three records with role information:

{
  "users": [
    {
      "id": "fe62d770-5886-11e4-8ed6-0800200c9a66",
      "login": "Kalo",
      "email": "kalohill@example.com",
      "display_name": "Kalo Hill",
      "role_ids": [1, 2, 3],
      "is_group": false,
      "is_remote": false,
      "is_superuser": true,
      "is_revoked": false,
      "last_login": "2014-05-04T02:32:00Z"
    },
    {
      "id": "07d9c8e0-5887-11e4-8ed6-0800200c9a66",
      "login": "Jean",
      "email": "jeanjackson@example.com",
      "display_name": "Jean Jackson",
      "role_ids": [2, 3],
      "inherited_role_ids": [5],
      "is_group": false,
      "is_remote": true,
      "is_superuser": false,
      "group_ids": [
        "2ca57e30-5887-11e4-8ed6-0800200c9a66"
      ],
      "is_revoked": false,
      "last_login": "2014-05-04T02:32:00Z"
    },
    {
      "id": "1cadd0e0-5887-11e4-8ed6-0800200c9a66",
      "login": "Amari",
      "email": "amariperez@example.com",
      "display_name": "Amari Perez",
      "role_ids": [2, 3],
      "inherited_role_ids": [5],
      "is_group": false,
      "is_remote": true,
      "is_superuser": false,
      "group_ids": [
        "2ca57e30-5887-11e4-8ed6-0800200c9a66"
      ],
      "is_revoked": false,
      "last_login": "2014-05-04T02:32:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 400,
    "offset": 1,
    "order": "desc",
    "filter": "example.com",
    "order_by": "last_login"
  }
}

For information about user object keys, refer to Users endpoints keys. The pagination keys are described in the Request format section, above.

For information about error responses, refer to RBAC service errors.