RBAC enables you to manage local users as well as those who are created remotely, on a directory service. With the users endpoints, you can get lists of users and create new local users.

Users keys

These keys are used with the RBAC v1 API's users endpoints.


Key	Explanation	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 the type of user. `is_group` is always be false for a user.	`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`	This is 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). Supports filtering by ID through query parameters. Authentication is required.

Request format

To request all users:

GET /usersCopied!

To request specific users, add a comma-separated list of user IDs:

GET /users?id=fe62d770-5886-11e4-8ed6-0800200c9a66,1cadd0e0-5887-11e4-8ed6-0800200c9a66Copied!

Example curl request:

curl GET 'https://$(puppet config print server):4433/rbac-api/v1/users' \
-H "X-Authentication:$(puppet-access show)"Copied!

Response format

The response is a JSON object that lists the metadata for all requested users. For example:

[{
  "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"
}]Copied!

GET /users/<sid>

Fetches specified, individual users by subject ID (<sid>). Authentication is required.

Request format

To request one user:

GET /users/<sid>Copied!

Example curl request for one user:

curl GET 'https://$(puppet config print server):4433/rbac-api/v1/users/c97c716a-5f42-49d8-b5a4-d0888a879d21' \
-H "X-Authentication:$(puppet-access show)"Copied!

To request multiple users, add a comma-separated list of user IDs:

GET /users?id=<sid>,<sid>Copied!

Example curl request for multiple users:

curl GET 'https://$(puppet config print server):4433/rbac-api/v1/users?id=c97c716a-5f42-49d8-b5a4-d0888a879d21,76351f96-3d89-4947-bde9-bc3d86542839' \
-H "X-Authentication:$(puppet-access show)"Copied!

Response format

For all users, the user contains an ID, a login, an email, a display name, a list of role-ids the user is directly assigned to, and the last login time in UTC-based ISO-8601 format (YYYY-MM-DDThh:mm:ssZ), or null if the user has not logged in yet. It also contains an "is_revoked" field, which, when set to true, prevents a user from authenticating.

For example:

{"id": "fe62d770-5886-11e4-8ed6-0800200c9a66",
"login": "Amari",
"email": "amariperez@example.com",
"display_name": "Amari Perez",
"role_ids": [1,2,3...],
"is_group" : false,
"is_remote" : false,
"is_superuser" : false,
"is_revoked": false,
"last_login": "2014-05-04T02:32:00Z"}Copied!

For remote users, the response contains two additional fields. The group_ids field contains IDs of groups from which the user inherits roles. The inherited_role_ids field lists inherited role IDs.

For example:

{"id": "07d9c8e0-5887-11e4-8ed6-0800200c9a66",
"login": "Jean",
"email": "jeanjackson@example.com",
"display_name": "Jean Jackson",
"role_ids": [2,3...],
"inherited_role_ids": [],
"is_group" : false,
"is_remote" : true,
"is_superuser" : false,
"group_ids": ["b28b8790-5889-11e4-8ed6-0800200c9a66"],
"is_revoked": false,
"last_login": "2014-05-04T02:32:00Z"}Copied!

GET /users/current

Fetches data about the current authenticated user, with the exact same behavior as GET /users/<sid>, except that <sid> is assumed from the authentication context. Authentication is required.

Request format

Example curl request:

curl GET 'https://$(puppet config print server):4433/rbac-api/v1/users/current' \
-H "X-Authentication:$(puppet-access show)"Copied!

Response format

Example response:

{"email":"",
  "is_revoked":false,
  "last_login":"2021-12-08T20:47:47.788Z",
  "is_remote":false,
  "login":"admin",
  "is_superuser":true,
  "id":"42bf351c-f9ec-40af-84ad-e976fec7f4bd",
  "role_ids":[1],
  "display_name":"Administrator",
  "is_group":false}Copied!

GET /users/<user-id>/tokens

Fetches a list of tokens for a given user and produces output in JSON format. Authentication required.

Request format

The request accepts these parameters:


Parameter	Definition
`limit`	Maximum number of records that can be returned. Defaults to return all records. Optional integer.
`offset`	Determines the first record to be returned. Defaults to `0`. Optional integer.
`order_by`	Determines the order by which records are returned. Is one of either `creation_date`, `expiration_date`, `last_active_date`, or `client`. Defaults to `creation_date`. Optional string.
`order`	Determines the sort order by specifying either `asc` or `desc`. Defaults to `asc`. Optional string.

Example curl request:

curl GET 'https://$(puppet config print server):4433/rbac-api/v1/users/c97c716a-5f42-49d8-b5a4-d0888a879d21/tokens' \
-H "X-Authentication:$(puppet-access show)"Copied!

Response format

Example response format:

{"items": [{
      "id": <token id>
      "creation_date": <ISO-8601>,
      "expiration_date":  <ISO-8601>,
      "last_active_date": <ISO-8601>,
      "client":  <client field>",
      "description:" <description field>,
      "session_timeout":  <number, present with timeout in minutes if session based token>,
      "label": <optional user label for token (unused feature for the most part)>
   }, ... 
 ],
 "pagination": {
      "limit": <present with value if limit applied>,
      "offset": <offset from start of collection>,
      "order_by":  <one of "creation_date", "expiration_date", "last_active_date", "client">,
      "order": <one of "asc", "desc">
      "total": <total number of records including limit and offset>
   }}Copied!

Error response

If a user with the provided identifier doesn't exist, the endpoint returns 404 Not Found.

POST /users

Creates a new local user. You can add the new user to user roles by specifying an array of roles in role_ids. You can set a password for the user in password. For the password to work in the PE console, it must be at least six characters. Authentication is required.

Request format

Accepts a JSON body containing entries for email, display_name, login, role_ids, and password. The password field is optional. The created account is not useful until the password is set.

For example:

{"login":"Kalo",
"email":"kalohill@example.com",
"display_name":"Kalo Hill",
"role_ids": [1,2,3],
"password": "yabbadabba"}Copied!

Example curl request:

curl POST 'https://$(puppet config print server):4433/rbac-api/v1/users' \
-H "X-Authentication: $(puppet-access show)"  \
-H "Content-type:   application/json" \
-d '{"login": "test",
     "email": "test@example.com", 
     "display_name": "Test User",
     "role_ids": [],
     "password": "Test123!"}'Copied!

Response format

If creation is successful, the endpoint returns 201 Created with a location header pointing to the new resource.

Error responses

If the email or login for the user conflicts with an existing user's login, the endpoint returns 409 Conflict.

PUT /users/<sid>

Replaces the user with the specified ID (<sid>) with a new user object. Authentication is required.

Request format

Accepts an updated user object with all keys provided when the object is received from the API. The behavior varies based on user type. All types have a role_id array that indicates the roles to assign to the user. An empty role_id array removes all roles directly assigned to the user.

These examples show what keys must be submitted. Keys marked with asterisks are the only ones that can be changed through the API.

An example for a local user:

{"id": "c8b2c380-5889-11e4-8ed6-0800200c9a66",
"login": "Amari",
"email": "amariperez@example.com",
"display_name": "Amari Perez",
"role_ids": [1, 2, 3],
"is_group" : false,
"is_remote" : false,
"is_superuser" : false,
"is_revoked": false,
"last_login": "2014-05-04T02:32:00Z"}Copied!

An example for a remote user:

{"id": "3271fde0-588a-11e4-8ed6-0800200c9a66",
"login": "Jean",
"email": "jeanjackson@example.com",
"display_name": "Jean Jackson",
"role_ids": [4, 1],
"inherited_role_ids": [],
"group_ids: [],
"is_group" : false,
"is_remote" : true,
"is_superuser" : false,
"is_revoked": false,
"last_login": "2014-05-04T02:32:00Z"}Copied!

Example curl request:

curl PUT 'https://$(puppet config print server):4433/rbac-api/v1/users/c97c716a-5f42-49d8-b5a4-d0888a879d21' \
-H "X-Authentication:$(puppet-access show)" \
-H "Content-type:   application/json" \
-d '{"id": "c97c716a-5f42-49d8-b5a4-d0888a879d21",
     "login": "replace-test",
     "email": "replace-test@example.com",
     "display_name": "Replaced User",
     "role_ids": [],
     "is_group": false,
     "is_remote": false,
     "is_superuser": false,
     "is_revoked": false,
     "last_login": "2014-05-04T02:32:00Z"}'Copied!

Response format

Returns 200 OK and the user object with the changes made. For example:

{"email":"replace-test@example.com",
  "is_revoked":false,
  "last_login":null,
  "is_remote":false,
  "login":"replace-test",
  "is_superuser":false,
  "id":"c97c716a-5f42-49d8-b5a4-d0888a879d21",
  "role_ids":[],
  "display_name":"Replaced User",
  "is_group":false}Copied!

Error responses

If the login for the user conflicts with an existing user login, the endpoint returns 409 Conflict.

DELETE /users/<sid>

Deletes the user with the specified ID (<sid>), regardless of whether they are a user defined in RBAC or a user defined by a directory service. In the case of directory service users, while this action removes a user from the console, that user is still able to log in (at which point they are re-added to the console) if they are not revoked. Authentication is required.

Remember: The admin user and the api_user cannot be deleted. The API user is for service-to-service authentication within PE. It cannot be used with the standard login, and it is only available through certificate-based authentication. The RBAC allow list identifies (by certname) the certificates you can use for API user authentication.

Request format

Example curl request:

curl DELETE 'https://$(puppet config print server):4433/rbac-api/v1/users/76351f96-3d89-4947-bde9-bc3d86542839' \
-H "X-Authentication:$(puppet-access show)"Copied!

See Usage notes for curl examples for information about forming curl commands.

Response format

If the user is successfully deleted, the endpoint returns 204 No Content.

Error responses

If the current user does not have the users:edit permission for this user group, the endpoint returns 403 Forbidden.

If a user with the provided identifier does not exist, the endpoint returns 404 Not Found.

POST /command/users/add-roles

Assign roles to a user.

Request format

The request accepts these keys:


Key	Definition
`user_id`	The ID of the user you want to assign roles to.
`role_ids`	A list of role IDs you want to assign to the user.

Example payload:

{ "user_id": <user-id>, "role_ids":[1,2,3] }Copied!

Example curl request:

curl POST 'https://$(puppet config print server):4433/rbac-api/v1/command/users/add-roles' \
-H "X-Authentication: $(puppet-access show)" \
-H "Content-type:   application/json" \
-d '{"user_id": "c97c716a-5f42-49d8-b5a4-d0888a879d21", "role_ids": [1]}'Copied!

Response format

Returns 204 No Content when the roles are assigned to the user.

An error in the standard format is returned for all other responses.

POST /command/users/remove-roles

Remove roles from a user.

Request format

The request accepts these keys:


Key	Definition
`user_id`	The ID of the user you want to remove the roles from.
`role_ids`	A list of role IDs you want to remove from the user.

Example payload:

{ "user_id": <user-id>, "role_ids":[1,2,3] }Copied!

Example curl request:

curl POST 'https://$(puppet config print server):4433/rbac-api/v1/command/users/remove-roles' \
-H "X-Authentication: $(puppet-access show)"  \
-H "Content-type:   application/json" \
-d '{"user_id": "c97c716a-5f42-49d8-b5a4-d0888a879d21", "role_ids": [1]}'Copied!

Response format

Returns 204 No Content if the user exists and there are no errors.

An error in the standard format is returned for all other responses.

POST /command/users/revoke

Revoke a user.

Request format

The request accepts this key:


Key	Definition
`user_id`	The UUID of the user you want to revoke.

Example curl request:

curl POST 'https://$(puppet config print server):4433/rbac-api/v1/command/users/revoke' \
-H "X-Authentication: $(puppet-access show)" \
-H "Content-type:   application/json" \
-d '{"user_id": "c97c716a-5f42-49d8-b5a4-d0888a879d21"}'Copied!

Response format

Returns 204 No Content when the user is revoked.

Returns 400 Bad Request if there is an error.

POST /command/users/reinstate

Reinstate a user after they have been revoked.

Request format


Key	Definition
`user_id`	The UUID of the user you want to reinstate.

Example curl request:

curl POST 'https://$(puppet config print server):4433/rbac-api/v1/command/users/reinstate' \
-H "X-Authentication: $(puppet-access show)" \
-H "Content-type:   application/json" \
-d '{"user_id": "c97c716a-5f42-49d8-b5a4-d0888a879d21"}'Copied!

Response format

Returns 204 No Content when the user is reinstated.

Returns 400 Bad Request if the payload doesn’t match the schema.

Returns 404 Not Found if the specified user doesn't exist.