Puppet User Management API Guide

Auth method: Token-based (PE RBAC token passed as X-Authentication header or query param token)

Setup steps

1. Authenticate to the PE console or use the /auth/token endpoint with a local or LDAP account credentials.
2. POST to https://:4433/rbac-api/v1/auth/token with JSON body containing login, password, and optionally lifetime.
3. Receive a token string in the response.
4. Include the token in subsequent requests as the HTTP header X-Authentication: or as query parameter ?token=.
5. Tokens expire based on the lifetime set at generation (default 1 hour); regenerate as needed.

List all users

• Method: GET
• URL: https://<PE_CONSOLE_HOST>:4433/rbac-api/v1/users
• Watch out for: Returns all users including remote (LDAP/AD) users. No pagination; large directories may return large payloads.

Request example

GET /rbac-api/v1/users HTTP/1.1
Host: <PE_CONSOLE_HOST>:4433
X-Authentication: <token>

Response example

[
  {
    "id": "uuid-1234",
    "login": "jdoe",
    "email": "jdoe@example.com",
    "display_name": "Jane Doe",
    "is_superuser": false,
    "is_revoked": false
  }
]

Get a single user

• Method: GET
• URL: https://<PE_CONSOLE_HOST>:4433/rbac-api/v1/users/{sid}
• Watch out for: Use the UUID (sid), not the login name, as the path parameter.

Request example

GET /rbac-api/v1/users/uuid-1234 HTTP/1.1
Host: <PE_CONSOLE_HOST>:4433
X-Authentication: <token>

Response example

{
  "id": "uuid-1234",
  "login": "jdoe",
  "email": "jdoe@example.com",
  "display_name": "Jane Doe",
  "role_ids": [1, 3],
  "is_superuser": false,
  "is_revoked": false
}

Create a local user

• Method: POST
• URL: https://<PE_CONSOLE_HOST>:4433/rbac-api/v1/users
• Watch out for: Cannot create remote (LDAP) users via this endpoint; remote users are imported from the directory service.

Request example

POST /rbac-api/v1/users HTTP/1.1
Content-Type: application/json
X-Authentication: <token>

{"login":"jdoe","email":"jdoe@example.com","display_name":"Jane Doe","role_ids":[1],"password":"S3cur3!"}

Response example

{
  "id": "uuid-5678",
  "login": "jdoe",
  "email": "jdoe@example.com",
  "display_name": "Jane Doe",
  "is_superuser": false,
  "is_revoked": false
}

Update a user

• Method: PUT
• URL: https://<PE_CONSOLE_HOST>:4433/rbac-api/v1/users/{sid}
• Watch out for: PUT requires the full user object including the id field in the body. Partial updates are not supported - omitting fields may reset them.

Request example

PUT /rbac-api/v1/users/uuid-1234 HTTP/1.1
Content-Type: application/json
X-Authentication: <token>

{"id":"uuid-1234","login":"jdoe","is_revoked":true}

Response example

{
  "id": "uuid-1234",
  "login": "jdoe",
  "is_revoked": true
}

Revoke a user (disable)

• Method: PUT
• URL: https://<PE_CONSOLE_HOST>:4433/rbac-api/v1/users/{sid}
• Watch out for: There is no dedicated DELETE endpoint for users; revocation (is_revoked: true) is the supported deactivation mechanism.

Request example

PUT /rbac-api/v1/users/uuid-1234 HTTP/1.1
Content-Type: application/json
X-Authentication: <token>

{"id":"uuid-1234","login":"jdoe","is_revoked":true}

Response example

{
  "id": "uuid-1234",
  "login": "jdoe",
  "is_revoked": true
}

Get current (authenticated) user

• Method: GET
• URL: https://<PE_CONSOLE_HOST>:4433/rbac-api/v1/users/current
• Watch out for: Returns the user associated with the token used in the request.

Request example

GET /rbac-api/v1/users/current HTTP/1.1
X-Authentication: <token>

Response example

{
  "id": "uuid-1234",
  "login": "admin",
  "is_superuser": true,
  "is_revoked": false
}

Generate auth token

• Method: POST
• URL: https://<PE_CONSOLE_HOST>:4433/rbac-api/v1/auth/token
• Watch out for: Token lifetime format uses duration strings (e.g., '1h', '24h'). Default lifetime is 1 hour. Tokens cannot be revoked individually via API - they expire naturally.

Request example

POST /rbac-api/v1/auth/token HTTP/1.1
Content-Type: application/json

{"login":"admin","password":"S3cur3!","lifetime":"1h"}

Response example

{
  "token": "eyJhbGciOiJSUzUxMiJ9..."
}

Assign roles to a user

• Method: PUT
• URL: https://<PE_CONSOLE_HOST>:4433/rbac-api/v1/users/{sid}
• Watch out for: Role assignment is done via the user PUT endpoint, not a separate roles-assignment endpoint. Provide the complete desired role_ids array; it replaces the existing list.

Request example

PUT /rbac-api/v1/users/uuid-1234 HTTP/1.1
Content-Type: application/json
X-Authentication: <token>

{"id":"uuid-1234","login":"jdoe","role_ids":[1,4]}

Response example

{
  "id": "uuid-1234",
  "login": "jdoe",
  "role_ids": [1, 4]
}

• Rate limits: No explicit rate limit documentation found in official Puppet Enterprise RBAC API docs.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No rate limit tiers or headers documented officially. Practical limits depend on PE server resources.

• Pagination method: none

• Default page size: 0

• Max page size: 0

• Pagination pointer: Not documented

• Webhooks available: No

• Webhook notes: Puppet Enterprise RBAC API does not expose webhook or event subscription functionality for user management events.

• Alternative event strategy: Use the PE Activity Service API (https://:4433/activity-api/v1) to poll audit logs for user-related events.

• SCIM available: No
• SCIM version: Not documented
• Plan required: Enterprise
• Endpoint: Not documented

Limitations:

• Puppet Enterprise does not natively expose a SCIM 2.0 endpoint.
• User provisioning from IdPs (e.g., Okta) is typically handled via LDAP/AD directory service integration, not SCIM.
• No official SCIM connector documented by Puppet as of the latest available documentation.

Provision a new local user by POSTing to /rbac-api/v1/users with login, display_name, email, password, and a role_ids array of valid integer role IDs fetched from GET /rbac-api/v1/roles.

Password is only accepted for local users;

remote (LDAP/AD) users are imported from the directory and cannot be created or have passwords set via this endpoint.

To revoke a user, first GET /rbac-api/v1/users/{sid} to retrieve the full current object, then PUT the same object back with is_revoked set to true.

The PUT endpoint requires the complete user object including the id field - partial updates are not supported, and omitting fields risks resetting them to defaults.

For audit workflows, poll the Activity Service at https://:4433/activity-api/v1/events?service_id=rbac with the same X-Authentication token.

Filter by subject_type=users and the target user's UUID to reconstruct an event trail.

The Activity Service is read-only and does not support webhooks;

all audit data must be retrieved by polling.

Provision a new local PE user and assign a role

1. POST /rbac-api/v1/auth/token with admin credentials to obtain a token.
2. GET /rbac-api/v1/roles to retrieve available role IDs and identify the target role.
3. POST /rbac-api/v1/users with login, email, display_name, password, and role_ids array.
4. Verify creation by GET /rbac-api/v1/users/{new_uuid}.

Watch out for: Password is only accepted for local users. The role_ids array must contain valid integer role IDs from the PE instance.

Revoke (disable) a user account

1. GET /rbac-api/v1/users to find the user's UUID by login name.
2. GET /rbac-api/v1/users/{sid} to retrieve the full current user object.
3. PUT /rbac-api/v1/users/{sid} with the full user object and is_revoked set to true.
4. Confirm by GET /rbac-api/v1/users/{sid} and verify is_revoked is true.

Watch out for: PUT requires the complete user object. Fetch the current state first to avoid accidentally resetting other fields.

Audit recent user activity via Activity Service

1. Obtain a valid RBAC token via POST /rbac-api/v1/auth/token.
2. GET https://:4433/activity-api/v1/events?service_id=rbac with X-Authentication header.
3. Filter returned events by subject_type=users and the relevant user UUID.
4. Parse event timestamps and descriptions to build an audit trail.

Watch out for: The Activity Service is a separate API on the same port (4433). It is read-only and does not support webhooks; polling is required.

The most common integration trap is treating the RBAC API like a standard REST API with PATCH support and pagination - it has neither. Every user update requires fetching the full current object first and PUTting it back in its entirety; skipping the prefetch step will silently overwrite fields including role assignments.

Token management is a second operational risk: tokens generated via /auth/token cannot be individually revoked through the API and expire only by their configured lifetime. A leaked or long-lived token has no API-side kill switch. Scope token lifetimes tightly and rotate them on a schedule.

Finally, the API is PE-only and port-specific (4433, not 8140). Integrations built against a PE instance will not work against open-source Puppet, and firewall rules that only open 8140 will silently block all RBAC API calls.