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 .