Users endpoints

With role-based access control (RBAC), you can manage local users and remote users (created on a directory service). Use the users endpoints to get lists of users, create local users, and delete, revoke, and reinstate users in PE.

You can:

GET /users: Get a list of all local and remote users.
GET /users/<sid>: Get information about specific users.
GET /users/current: Get information about the current authenticated user.
GET /users/<sid>/tokens: Get a list of tokens for a user.
POST /users: Create a local user.
PUT /users/<sid>: Edit a user.
DELETE /users/<sid>: Delete a user from the PE console.
POST /command/users/add-roles: Assign roles to a user.
POST /command/users/remove-roles: Remove roles from a user.
POST /command/users/revoke: Revoke a user's PE access.
POST /command/users/reinstate: Reinstate a revoked user.

Tip: You'll want to be familiar with the Users endpoints keys that appear in these endpoints' requests and responses.

Users endpoints keys

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


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` or `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` or `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"]`
`identity_provider_id`	The UUID of the LDAP identity provider associated with the user.	`"4522ca7e-5623-11ed-bdc3-0242ac120002"`

GET /users

Fetches all local and remote users, including the superuser. You can also query specific users by user ID. Authentication is required.

Important: You can use the v1 GET /users endpoint to query all users or specific users by ID; however, the v2 GET /users endpoint provides more query options and control over the response content.

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/v1/users" -H "X-Authentication:$(puppet-access show)"

To query specific users, append a comma-separated list of user IDs:

curl "https://$(puppet config print server):4433/rbac-api/v1/users?id=<SID>,<SID>" -H "X-Authentication:$(puppet-access show)"

Response format

The response is a JSON object that contains 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"
}]

For information about keys in the response, refer to Users endpoints keys.

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

GET /users/<sid>

Fetches information about specific users identified by subject ID (<sid>). Authentication is required.

Request format

When Forming RBAC API requests to this endpoint, provide authentication and specify a user ID, such as:

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

To request multiple users, append a comma-separated list of user IDs, such as

curl "https://$(puppet config print server):4433/rbac-api/v1/users?id=<SID>,<SID>" -H "X-Authentication:$(puppet-access show)"

Tip: Querying multiple users technically calls the GET /users endpoint with the id parameter.

Response format

The response is a JSON object that contains metadata for the requested user (or users). For example, this response is for a local user:

{"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"}

And this response is for a remote user:

{"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"}

For information about keys in the response, refer to Users endpoints keys.

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

GET /users/current

Fetches data about the current authenticated user. The user's ID is assumed from the authentication context. 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/v1/users/current" -H "X-Authentication:$(puppet-access show)"

Response format

The response is the same as GET /users/<sid>.

GET /users/<sid>/tokens

Fetches a list of tokens for a given user. Authentication required.

Request format

When Forming RBAC API requests to this endpoint, you must supply a user ID in the URI path, such as:

https://$(puppet config print server):4433/rbac-api/v1/users/c97c716a-5f42-49d8-b5a4-d0888a879d21/tokens

You can append these optional parameters to the request:


Parameter	Definition
`limit`	An integer specifying the maximum number of records to return. If omitted, all records are returned.
`offset`	Specify a zero-indexed integer to specify the index value of the first record to return. If omitted, the default is position `0` (the first record). For example, `offset=5` would start from the 6th record.
`order_by`	Specify one of the following strings to define the order in which records are returned: `creation_date` `expiration_date` `last_active_date` `client` If omitted, the default is `creation_date`.
`order`	Determines the sort order as either ascending (`asc`) or descending (`desc`). If omitted, the default is `asc`.

For example:

curl 'https://$(puppet config print server):4433/rbac-api/v1/users/<SID>/tokens?limit=20' \
-H "X-Authentication:$(puppet-access show)"

Response format

The response is a JSON object describing each token and the pagination information from the request.

Tokens are containing in an items array. Each token is represented as an object using these keys:

id: The token's ID
creation_date: The date and time the token was created in ISO-8601 format.
expiration_date: The date and time the token expires (or expired) in ISO-8601 format.
last_active_date: The date and time the token was last used in ISO-8601 format.
client: Client information.
description: Arbitrary description information.
session_timeout: An integer, present with a timeout (in minutes), if this is a session-based token.
label: A label, if one was supplied at creation. Refer to Set a token-specific label.

The pagination object reiterates the query pameters from the request as well as the total number of records available (regardless of limit or offset).

For example:

{"items": [{
      "id": <token_id>
      "creation_date": <ISO-8601>,
      "expiration_date":  <ISO-8601>,
      "last_active_date": <ISO-8601>,
      "client":  "",
      "description": "",
      "session_timeout": ,
      "label": ""
   }, ... 
 ],
 "pagination": {
      "limit": 20,
      "offset": 0,
      "order_by": "creation_date",
      "order": "asc"
      "total": 25
   }
}

Error response

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

For other errors, refer to RBAC service errors.

POST /users

Create a local user. Authentication is required.

Request format

When Forming RBAC API requests to this endpoint, the content type is application/json. The body must be a JSON object using the following keys:

email: Specify the user's email address.
display_name: The user's name as you want it shown in the console.
login: The username for the user to use to login.
role_ids: An array of role IDs defining the roles that you want to assign to the new user. An empty array is valid, but the user can't do anything in PE if they are not assigned to any roles.
password: A password the user can use to login. For the password to work in the PE console, it must be at least six characters. This field is optional, however user accounts are not usable until a password is set. You can also use the Passwords endpoints to generate a password reset token the user can use to login for the first time.

For example:

curl -X POST 'https://$(puppet config print server):4433/rbac-api/v1/users' \
-H "X-Authentication: $(puppet-access show)"  \
-H "Content-type:   application/json" \
-d '{"login": "Kalo",
     "email": "kalohill@example.com", 
     "display_name": "Kalo Hill",
     "role_ids": [1123,6643,1218],
     "password": "Welc0me!"}'

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 a 409 Conflict response.

For other errors, refer to RBAC service errors.

PUT /users/<sid>

Replace the content of the specified user object. For example, you can update a user's email address or role assignments. Authentication is required.

Request format

When Forming RBAC API requests to this endpoint, the content type is application/json. The body must be a JSON object using all keys supplied in the GET /users/<sid> endpoint response, modified as needed to update the user. For descriptions of each key, refer to Users endpoints keys. Not all keys can be updated, such as last_login.

The role_ids array indicates the roles to assign to the user. An empty role_ids array removes all roles directly assigned to the user.

An example, this JSON body is 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"}

And this body is 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"}

Here is an example of a complete curl request to this endpoint:

curl -X 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"}'

Response format

Returns 200 OK and a user object showing 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}

Error responses

If the user's login user conflicts with an existing user login, the endpoint returns a 409 Conflict response.

For other errors, refer to RBAC service errors.

DELETE /users/<sid>

Deletes the user with the specified ID, regardless of whether they are a user defined in PE RBAC (local) or a user defined by a directory service (remote). Authentication is required.

Remember: The admin user and the api_user can't 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

When Forming RBAC API requests to this endpoint, the URI path must include the ID of the user you want to delete from the PE console. For example:

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

Response format

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

Important: When removing directory service users (remote users), this action removes the user from the PE console, but the user is still able to log in if they are not revoked. When a non-revoked directory service user logs in, their account is re-added to the console. Make sure to use the POST /command/users/revoke endpoint to revoke the user's access.

Error responses

If the requesting user (based on the authentication in the request) does not have the users:edit permission for the specified user, the endpoint returns a 403 Forbidden response.

If there is no user with the provided ID, the endpoint returns a 404 Not Found response.

For other errors, refer to RBAC service errors.

POST /command/users/add-roles

Assign roles to a user.

Request format

When Forming RBAC API requests to this endpoint, the content type is application/json. The body must be a JSON object using the following keys:

user_id: The ID of the user you want to assign roles to.
role_ids: An array of role IDs defining the roles that you want to assign to the user. An empty array is valid, but the user can't do anything in PE if they are not assigned to any roles.

Example payload:

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

Example curl request:

curl -X 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]}'

Tip: To assign multiple users to the same role at once, use the POST /command/roles/add-users endpoint.

Response format

Returns 204 No Content if the roles are successfully assigned to the user.

For errors, refer to RBAC service errors.

POST /command/users/remove-roles

Remove roles from a user.

Request format

When Forming RBAC API requests to this endpoint, the content type is application/json. The body must be a JSON object using the following keys:

user_id: The ID of the user you want to remove roles from.
role_ids: An array of role IDs defining the roles that you want to remove from the user.

Example payload:

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

Example curl request:

curl -X 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]}'

Response format

Returns 204 No Content if the user exists and the roles are successfully unassigned.

For errors, refer to RBAC service errors.

POST /command/users/revoke

Revoke a user's access to PE.

Request format

When Forming RBAC API requests to this endpoint, the content type is application/json. The body must be a JSON object containing the user_id key, which specifies the ID of the user you want to revoke.

Example curl request:

curl -X 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"}'

Response format

Returns 204 No Content if the user is revoked successfully.

For errors, refer to RBAC service errors.

POST /command/users/reinstate

Reinstate a user after they have been revoked.

Request format

When Forming RBAC API requests to this endpoint, the content type is application/json. The body must be a JSON object containing the user_id key, which specifies the UUID of the user you want to reinstate.

Example curl request:

curl -X 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"}'

Response format

Returns 204 No Content if the user is successfully reinstated.

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

For other errors, refer to RBAC service errors.

Was this page helpful?

We’re sorry to hear that!
Please tell us why so we can help. Enter your feedback and email. This form is sent to the Puppet docs team. We ask for your email as we might contact you regarding your feedback. If you need help with the product itself, visit Puppet Support or ask in Puppet Community on Slack. Feedback:

Email Address:

To learn about how Puppet uses your personal information, visit our privacy policy.

If you leave us your email, we may contact you regarding your feedback. For more information on how Puppet uses your personal information, see our privacy policy.

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project.