Rancher User Management API Guide

Auth method: Bearer token (API key - username:password encoded as Basic Auth or Bearer token in Authorization header)

Setup steps

1. Log in to the Rancher UI as an admin or user.
2. Navigate to User Avatar (top-right) > API & Keys.
3. Click 'Add Key', optionally set an expiry and description.
4. Copy the Access Key (username) and Secret Key (password) - the secret is shown only once.
5. Use the Access Key as the Bearer token directly, or combine as Basic Auth: base64(accessKey:secretKey).
6. Include in requests: Authorization: Bearer accessKey:secretKey or Authorization: Basic <base64(accessKey:secretKey)>.

Required scopes

List all users

• Method: GET
• URL: https://<rancher-server>/v3/users
• Watch out for: Returns only local users by default; external auth provider users appear only after they have logged in at least once.

Request example

GET /v3/users
Authorization: Bearer <accessKey:secretKey>

Response example

{
  "type": "collection",
  "data": [
    {"id":"user-abc12","username":"admin","enabled":true}
  ],
  "pagination": {"limit":20,"total":1}
}

Get a specific user

• Method: GET
• URL: https://<rancher-server>/v3/users/<userId>
• Watch out for: User ID format is 'user-'; do not confuse with principalId.

Request example

GET /v3/users/user-abc12
Authorization: Bearer <accessKey:secretKey>

Response example

{
  "id": "user-abc12",
  "username": "jdoe",
  "displayName": "Jane Doe",
  "enabled": true,
  "principalIds": ["local://user-abc12"]
}

Create a local user

• Method: POST
• URL: https://<rancher-server>/v3/users
• Watch out for: Only creates local auth users. External IdP users are provisioned on first login via the configured auth provider.

Request example

POST /v3/users
Content-Type: application/json

{"username":"jdoe","password":"S3cur3!","displayName":"Jane Doe","mustChangePassword":true}

Response example

{
  "id": "user-xyz99",
  "username": "jdoe",
  "enabled": true,
  "mustChangePassword": true
}

Update a user (e.g., disable account)

• Method: PUT
• URL: https://<rancher-server>/v3/users/<userId>
• Watch out for: PUT replaces the full object; use all existing fields to avoid unintentional resets. PATCH is not supported on this resource.

Request example

PUT /v3/users/user-xyz99
Content-Type: application/json

{"enabled":false}

Response example

{
  "id": "user-xyz99",
  "username": "jdoe",
  "enabled": false
}

Delete a user

• Method: DELETE
• URL: https://<rancher-server>/v3/users/<userId>
• Watch out for: Deleting a user does not revoke their active tokens immediately; tokens must be separately deleted via /v3/tokens.

Request example

DELETE /v3/users/user-xyz99
Authorization: Bearer <accessKey:secretKey>

Response example

HTTP 204 No Content

Assign global role to user

• Method: POST
• URL: https://<rancher-server>/v3/globalrolebindings
• Watch out for: globalRoleId 'user' grants standard user access; 'admin' grants full admin. Verify available role IDs via GET /v3/globalroles.

Request example

POST /v3/globalrolebindings
Content-Type: application/json

{"globalRoleId":"user","userId":"user-xyz99"}

Response example

{
  "id": "grb-abc01",
  "globalRoleId": "user",
  "userId": "user-xyz99"
}

List user tokens (API keys)

• Method: GET
• URL: https://<rancher-server>/v3/tokens?userId=<userId>
• Watch out for: Token secret values are never returned after creation. Only admins can list tokens for other users.

Request example

GET /v3/tokens?userId=user-xyz99
Authorization: Bearer <accessKey:secretKey>

Response example

{
  "type": "collection",
  "data": [
    {"id":"token-abc","userId":"user-xyz99","expired":false}
  ]
}

Set/change user password

• Method: POST
• URL: https://<rancher-server>/v3/users/<userId>?action=setpassword
• Watch out for: This action endpoint is only available for local auth users. Calling it on an external IdP-backed user will return an error.

Request example

POST /v3/users/user-xyz99?action=setpassword
Content-Type: application/json

{"newPassword":"N3wP@ss!"}

Response example

HTTP 200 OK
{
  "id": "user-xyz99",
  "mustChangePassword": false
}

• Rate limits: Rancher does not publish explicit API rate limits in official documentation. Rate limiting is not a documented built-in feature of the Rancher API as of the latest docs.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No documented rate limits or rate-limit response headers found in official Rancher docs. Operators may impose rate limits via ingress/load balancer configuration externally.

• Pagination method: offset

• Default page size: 20

• Max page size: 1000

• Pagination pointer: limit / marker

• Webhooks available: No

• Webhook notes: Rancher does not provide a native outbound webhook system for user management events in its official documentation.

• Alternative event strategy: Use Rancher's audit logging feature (audit-log) to capture user lifecycle events, or poll the /v3/users and /v3/tokens endpoints. Kubernetes-native event watching via the Rancher-generated kubeconfig is also possible for cluster-scoped events.

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

Limitations:

• Rancher does not have a native SCIM 2.0 endpoint.
• User provisioning from external IdPs (Okta, Entra ID) is handled via SAML/OIDC authentication; users are created in Rancher on first login.
• Automated deprovisioning requires disabling/deleting users via the Rancher REST API or disabling them in the upstream IdP (which prevents login but does not delete the Rancher user record).
• No official SCIM connector or SCIM-compatible endpoint is documented by SUSE/Rancher as of the latest docs.

Three high-value automation scenarios emerge from the API surface.

First, provisioning a local user requires a POST to /v3/users followed by a separate POST to /v3/globalrolebindings - without the binding, the user can authenticate but has zero access to any cluster or project.

Second, offboarding a departing user requires both a PUT to /v3/users/ with enabled:false and explicit DELETE calls against every token returned by GET /v3/tokens?userId=; setting enabled:false alone leaves existing API tokens valid and callable.

Third, access audits require paginated GETs across /v3/users, /v3/globalrolebindings, and /v3/clusterroletemplatebindings, joined on userId - and external IdP users who have never completed a first login will be absent from /v3/users entirely, creating a structural blind spot in audit coverage.

PUT semantics apply to updates (PATCH is unsupported on user resources); always submit the full user object to avoid unintentional field resets.

Create a local user and assign standard user role

1. POST /v3/users with {username, password, displayName, mustChangePassword:true} to create the user.
2. Note the returned user id (e.g., user-xyz99).
3. POST /v3/globalrolebindings with {globalRoleId:'user', userId:'user-xyz99'} to grant standard user access.
4. Optionally POST /v3/clusterroletemplatebindings to grant cluster-level access.

Watch out for: Without a globalRoleBinding, the new user can log in but has no access to any clusters or projects.

Disable a departing user and revoke their API tokens

1. GET /v3/users?username= to find the user's id.
2. PUT /v3/users/ with {enabled:false} to disable the account.
3. GET /v3/tokens?userId= to list all active tokens.
4. DELETE /v3/tokens/ for each token returned to fully revoke access.

Watch out for: Setting enabled:false alone does not invalidate existing API tokens; both steps are required for complete offboarding.

List all users and their global role bindings for an audit

1. GET /v3/users?limit=1000 to retrieve all user records (paginate using marker if total > 1000).
2. GET /v3/globalrolebindings?limit=1000 to retrieve all global role assignments.
3. Join on userId field to map each user to their assigned global roles.
4. GET /v3/globalroles to resolve globalRoleId values to human-readable role names.

Watch out for: External IdP users who have never logged in will not appear in /v3/users, creating a gap in audit coverage for newly provisioned IdP accounts.

The Rancher API is well-structured for point operations but carries several compounding caveats for identity graph construction.

External IdP users (Okta, Entra ID, LDAP) are not pre-provisionable - they materialize in /v3/users only after first login, meaning any identity graph built solely from the API will undercount federated identities until each user has authenticated at least once.

Rancher has no native SCIM 2.0 endpoint; automated deprovisioning from an IdP does not propagate a delete or disable to the Rancher user record, requiring a separate API call or manual action.

Token lifecycle is decoupled from account state: disabling a user does not revoke tokens, and tokens with no TTL persist indefinitely until explicitly deleted. Global role bindings and cluster/project role bindings are separate resources, so a complete picture of a user's effective permissions requires resolving at minimum three collections.

These gaps make Rancher a non-trivial node in any identity graph - an MCP server with 60+ deep IT/identity integrations can normalize these fragmented collections into a unified access model, but the underlying API constraints remain and must be accounted for in any sync or reconciliation logic.