Pulumi User Management API Guide

Auth method: Bearer token (Pulumi Cloud access token passed as Authorization header)

Setup steps

1. Log in to Pulumi Cloud (app.pulumi.com).
2. Navigate to your user avatar → Access Tokens.
3. Click 'Create token', give it a name, and copy the generated token.
4. Pass the token in API requests as the header: Authorization: token .
5. For org-scoped operations, ensure the token belongs to a user with appropriate org role (Admin or Member).

List organization members

• Method: GET
• URL: https://api.pulumi.com/api/orgs/{org}/members
• Watch out for: Returns only members of the specified org; token must belong to an org admin.

Request example

GET /api/orgs/myorg/members
Authorization: token pul-abc123

Response example

{
  "members": [
    {
      "role": "admin",
      "user": {
        "githubLogin": "jdoe",
        "name": "Jane Doe",
        "avatarUrl": "https://..."
      }
    }
  ]
}

Get organization member

• Method: GET
• URL: https://api.pulumi.com/api/orgs/{org}/members/{username}
• Watch out for: Username is the Pulumi Cloud login handle, not email.

Request example

GET /api/orgs/myorg/members/jdoe
Authorization: token pul-abc123

Response example

{
  "role": "member",
  "user": {
    "githubLogin": "jdoe",
    "name": "Jane Doe",
    "avatarUrl": "https://..."
  }
}

Update organization member role

• Method: PATCH
• URL: https://api.pulumi.com/api/orgs/{org}/members/{username}
• Watch out for: Only 'admin' and 'member' are valid role values.

Request example

PATCH /api/orgs/myorg/members/jdoe
Authorization: token pul-abc123
Content-Type: application/json

{"role": "admin"}

Response example

HTTP 200 OK
{}

Remove organization member

• Method: DELETE
• URL: https://api.pulumi.com/api/orgs/{org}/members/{username}
• Watch out for: Removing a member does not delete their Pulumi account; it only removes org membership.

Request example

DELETE /api/orgs/myorg/members/jdoe
Authorization: token pul-abc123

Response example

HTTP 204 No Content

List teams in organization

• Method: GET
• URL: https://api.pulumi.com/api/orgs/{org}/teams
• Watch out for: Teams are an Enterprise/Team plan feature; endpoint may return empty on Individual plan.

Request example

GET /api/orgs/myorg/teams
Authorization: token pul-abc123

Response example

{
  "teams": [
    {"kind": "pulumi", "name": "platform-team",
     "displayName": "Platform Team"}
  ]
}

Add member to team

• Method: POST
• URL: https://api.pulumi.com/api/orgs/{org}/teams/{team}/members
• Watch out for: User must already be an org member before being added to a team.

Request example

POST /api/orgs/myorg/teams/platform-team/members
Authorization: token pul-abc123
Content-Type: application/json

{"memberLogin": "jdoe"}

Response example

HTTP 200 OK
{}

Remove member from team

• Method: DELETE
• URL: https://api.pulumi.com/api/orgs/{org}/teams/{team}/members/{username}
• Watch out for: Does not remove the user from the organization, only from the team.

Request example

DELETE /api/orgs/myorg/teams/platform-team/members/jdoe
Authorization: token pul-abc123

Response example

HTTP 204 No Content

List organization access tokens

• Method: GET
• URL: https://api.pulumi.com/api/orgs/{org}/tokens
• Watch out for: Token values are not returned after creation; only metadata is listed.

Request example

GET /api/orgs/myorg/tokens
Authorization: token pul-abc123

Response example

{
  "tokens": [
    {"id": "tok-xyz", "description": "CI token",
     "lastUsed": "2024-01-15T10:00:00Z"}
  ]
}

• Rate limits: Pulumi Cloud REST API enforces rate limits but does not publicly document specific numeric thresholds per plan tier.

• Rate-limit headers: Unknown

• Retry-After header: Unknown

• Rate-limit notes: No publicly documented rate limit values found in official docs. Implement exponential backoff on HTTP 429 responses.

• Pagination method: token

• Default page size: Not documented

• Max page size: Not documented

• Pagination pointer: continuationToken

• Webhooks available: No

• Webhook notes: Pulumi Cloud does not expose a general-purpose webhook system for user-management events in its official documentation.

• Alternative event strategy: Use the REST API to poll for membership changes, or rely on SCIM provisioning events from your IdP.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: https://api.pulumi.com/scim/v2/{org}

• Supported operations: GET /Users, GET /Users/{id}, POST /Users, PUT /Users/{id}, PATCH /Users/{id}, DELETE /Users/{id}, GET /Groups, GET /Groups/{id}, POST /Groups, PUT /Groups/{id}, PATCH /Groups/{id}, DELETE /Groups/{id}

Limitations:

• Requires Enterprise plan.
• SSO (SAML) must be configured and enabled before SCIM can be activated.
• Supported IdPs documented: Okta and Microsoft Entra ID (Azure AD).
• SCIM Groups map to Pulumi Teams; team names must be unique within the org.
• Deprovisioning a SCIM user removes them from the org but does not delete the Pulumi account.
• SCIM token is a separate org-level token generated in the Pulumi Cloud SCIM settings page.

Three automation scenarios are well-supported by the current API surface.

Deprovision via REST: Call DELETE /api/orgs/{org}/members/{username} with an Admin token, then confirm with a GET expecting a 404. Critical caveat: this call does not revoke the user's personal access tokens - those remain valid and must be audited and revoked separately.

Provision via SCIM (Okta): Generate a SCIM token in org SCIM settings, configure Okta with base URL https://api.pulumi.com/scim/v2/{org}, enable Push Users and Push Groups. Okta group pushes create Pulumi Teams automatically; team name collisions with pre-existing Pulumi Teams will cause provisioning failures and must be resolved before sync.

Role promotion via REST: PATCH /api/orgs/{org}/members/{username} with body {"role": "admin"}. Only admin and member are valid values. The target user must have already accepted org membership; the endpoint will reject promotion of pending invitees.

Deprovision a user via REST API

1. Authenticate with an org Admin access token.
2. Call DELETE /api/orgs/{org}/members/{username} to remove the user from the organization.
3. Optionally, call DELETE /api/orgs/{org}/teams/{team}/members/{username} for each team first (membership is removed automatically on org removal).
4. Verify removal by calling GET /api/orgs/{org}/members/{username} and confirming 404.

Watch out for: Removing a member via REST does not revoke their personal Pulumi access tokens; those must be managed separately or via SCIM deprovisioning.

Automate user provisioning via SCIM (Okta)

1. Ensure Enterprise plan is active and SAML SSO is configured for the org.
2. In Pulumi Cloud org settings, navigate to SCIM and generate a SCIM access token.
3. In Okta, add the Pulumi app and configure SCIM provisioning with base URL https://api.pulumi.com/scim/v2/{org} and Bearer token auth.
4. Enable 'Push Users' and 'Push Groups' in Okta to sync users and teams to Pulumi.
5. Assign users/groups in Okta; Pulumi will auto-provision org membership and team assignments.

Watch out for: SCIM Groups in Okta map to Pulumi Teams; the team must not already exist with a conflicting name in Pulumi Cloud.

Promote a member to org Admin

1. Authenticate with an existing org Admin access token.
2. Call PATCH /api/orgs/{org}/members/{username} with body {"role": "admin"}.
3. Confirm the change by calling GET /api/orgs/{org}/members/{username} and verifying role is 'admin'.

Watch out for: Only existing org members can be promoted; the user must have accepted org membership first.

The most consequential API gap is the absence of token lifecycle management in the REST surface: DELETE /api/orgs/{org}/members/{username} removes org membership but leaves all personal access tokens issued to that user fully operational. Any automation pipeline that treats the DELETE response as a complete offboarding signal is incorrect.

A secondary trap is the dual base-path architecture - REST lives under /api/orgs/{org} while SCIM lives under /scim/v2/{org}; mixing these paths produces authentication errors that are not always self-explanatory.

Finally, webhooks for user-management events are not available; any identity graph that needs to stay current must poll GET /api/orgs/{org}/members on a schedule or rely on IdP-side SCIM event logs as the authoritative change feed.