Summary
Pulumi Cloud has a distinct account type — a user whose account is managed by an organization (created through SAML JIT provisioning or SCIM). These accounts are subject to several restrictions that ordinary accounts are not. None of this is documented anywhere under content/docs/administration/, and searching the docs tree for "org-managed", "managed user", or equivalent returns nothing.
This matters because the restrictions are user-visible, produce hard errors, and are currently unresolvable from the documentation. A user who hits one has nothing to read.
Behaviors that need documenting
Observable product behavior, verified against the service:
- An org-managed user can only belong to the organization that manages them, plus organizations related to it through a parent/child multi-org relationship. Invites to unrelated organizations are rejected.
- An org-managed user cannot connect additional identity providers. The exception is a user managed by a multi-org, who can connect SAML identities for related organizations only — no OAuth (GitHub/GitLab/Atlassian/Google) identities in either case.
- An org-managed user cannot create organizations.
- Becoming org-managed is destructive. The migration removes the user from their other organizations and deletes their non-SAML linked identities. This is closely related to the existing warning in SAML admin — "When a user stops being a SAML admin, they will automatically lose all other login methods" — which is currently the only place in the docs where anything like this appears.
- Org-managed status is not the same as SAML org membership. An account created by logging into a SAML org is org-managed. A pre-existing Pulumi account that later joins a SAML org by invite is not — it stays an ordinary account with an added SAML identity. There is a separate opt-in migration in Account settings to convert. The docs never distinguish these, and the distinction determines whether restrictions 1–3 apply.
Suggested placement
A new page under content/docs/administration/access-identity/ (sibling to saml/ and scim/), cross-linked from:
organizations-teams/accounts.md — the Adding New Identities section presents identity linking as unconditional; it should note that org-managed accounts cannot do this.access-identity/scim/_index.md — SCIM is how most org-managed users get created.access-identity/saml/_index.md.
Related gaps found in the same area
Filing together since they surfaced from one investigation and touch adjacent pages. Happy to split into separate issues if preferred.
A. Inaccurate statement in the Pulumi Cloud FAQ
content/docs/support/faq/pulumi-cloud.md, "How do I link an existing Pulumi account to my company's organization?":
To join your company's organization, you must sign in with the identity provider that organization is backed by (for example, GitHub, GitLab, SAML/SSO, or email).
This is incorrect for the OAuth-backed organizations (GitHub, GitLab, Atlassian). For those, you must have the identity linked to your account; the identity provider you actually sign in with is irrelevant. Someone who signs in with email and has an Atlassian identity linked has full access to a Bitbucket-backed organization.
It is true for SAML, where authenticating through the IdP is what establishes the identity — so the fix is to distinguish the two cases rather than delete the sentence. The following sentence already gets it right ("connect that identity provider, then accept the organization invite"), so the two currently contradict each other.
Separately, the fallback advice in that answer — "If this fails, delete your account, then accept the organization invite" — is drastic for what is usually just an unlinked identity, and deleting an account has consequences the note below it describes. Worth reconsidering.
B. Nothing documents that identity linking can be unavailable
Adding New Identities describes connecting additional identities as always available. In practice the controls can be absent — org-managed status is one cause; a deployment without that provider's OAuth credentials configured is another. A short "if you don't see these options" subsection would resolve a class of support questions.
C. Bitbucket: the admin requirement is understated
Bitbucket identity provider says a workspace admin must grant the OAuth app read access. It doesn't say that the person performing the change in Pulumi must themselves be an admin or owner of the Bitbucket workspace — a contributor or plain member gets a hard error. Worth stating explicitly, alongside the fact that a personal Bitbucket account with no workspace won't work.
D. Backend membership is not the same as Pulumi organization membership
On per-member billing plans, being a member of the backing GitHub org / GitLab group / Bitbucket workspace does not by itself make you a member of the Pulumi organization — it makes you eligible, and an organization admin still has to add you. Older plans behave differently and grant membership directly.
Bitbucket identity provider gestures at this ("the admin can see a list of Bitbucket workspace members that they can add or invite") but never names the two-tier model, and it isn't stated for GitHub or GitLab at all. This is a common source of "I'm in the GitHub org, why can't I see anything?"
E. Switching away from SAML is destructive and undocumented
Disconnecting identity providers correctly explains that you remove SAML by selecting a different identity provider. It does not warn that doing so discards the organization's SAML identities, its SAML member roster, and its SCIM access token — meaning SCIM must be reconfigured with a newly issued token and users re-provisioned if you switch back. Given the SCIM docs are otherwise thorough, this deserves a warning note on both pages.
F. Converting an organization to SAML can fail for the admin doing it
The SAML setup guides walk the reader to Membership Requirements → Change requirements and stop. The change is rejected if the admin performing it belongs to other, unrelated Pulumi organizations. This produces a confusing error at the last step of an otherwise well-documented setup flow, and should be listed as a prerequisite.
G. Terminology is inconsistent across surfaces
The docs say "identity provider" and "Membership Requirements"; the console uses both that phrasing and "organization backend"; the API calls it the organization backend. For Bitbucket specifically, the docs and console alternate between "Bitbucket" and "Atlassian" (the connect control is labeled Connect Atlassian, and a linked identity appears as Atlassian) without ever stating they're the same thing. A short glossary note, or simply saying "Atlassian (Bitbucket)" on first use, would help.
Summary
Pulumi Cloud has a distinct account type — a user whose account is managed by an organization (created through SAML JIT provisioning or SCIM). These accounts are subject to several restrictions that ordinary accounts are not. None of this is documented anywhere under
content/docs/administration/, and searching the docs tree for "org-managed", "managed user", or equivalent returns nothing.This matters because the restrictions are user-visible, produce hard errors, and are currently unresolvable from the documentation. A user who hits one has nothing to read.
Behaviors that need documenting
Observable product behavior, verified against the service:
Suggested placement
A new page under
content/docs/administration/access-identity/(sibling tosaml/andscim/), cross-linked from:organizations-teams/accounts.md— the Adding New Identities section presents identity linking as unconditional; it should note that org-managed accounts cannot do this.access-identity/scim/_index.md— SCIM is how most org-managed users get created.access-identity/saml/_index.md.Related gaps found in the same area
Filing together since they surfaced from one investigation and touch adjacent pages. Happy to split into separate issues if preferred.
A. Inaccurate statement in the Pulumi Cloud FAQ
content/docs/support/faq/pulumi-cloud.md, "How do I link an existing Pulumi account to my company's organization?":This is incorrect for the OAuth-backed organizations (GitHub, GitLab, Atlassian). For those, you must have the identity linked to your account; the identity provider you actually sign in with is irrelevant. Someone who signs in with email and has an Atlassian identity linked has full access to a Bitbucket-backed organization.
It is true for SAML, where authenticating through the IdP is what establishes the identity — so the fix is to distinguish the two cases rather than delete the sentence. The following sentence already gets it right ("connect that identity provider, then accept the organization invite"), so the two currently contradict each other.
Separately, the fallback advice in that answer — "If this fails, delete your account, then accept the organization invite" — is drastic for what is usually just an unlinked identity, and deleting an account has consequences the note below it describes. Worth reconsidering.
B. Nothing documents that identity linking can be unavailable
Adding New Identities describes connecting additional identities as always available. In practice the controls can be absent — org-managed status is one cause; a deployment without that provider's OAuth credentials configured is another. A short "if you don't see these options" subsection would resolve a class of support questions.
C. Bitbucket: the admin requirement is understated
Bitbucket identity provider says a workspace admin must grant the OAuth app read access. It doesn't say that the person performing the change in Pulumi must themselves be an admin or owner of the Bitbucket workspace — a contributor or plain member gets a hard error. Worth stating explicitly, alongside the fact that a personal Bitbucket account with no workspace won't work.
D. Backend membership is not the same as Pulumi organization membership
On per-member billing plans, being a member of the backing GitHub org / GitLab group / Bitbucket workspace does not by itself make you a member of the Pulumi organization — it makes you eligible, and an organization admin still has to add you. Older plans behave differently and grant membership directly.
Bitbucket identity provider gestures at this ("the admin can see a list of Bitbucket workspace members that they can add or invite") but never names the two-tier model, and it isn't stated for GitHub or GitLab at all. This is a common source of "I'm in the GitHub org, why can't I see anything?"
E. Switching away from SAML is destructive and undocumented
Disconnecting identity providers correctly explains that you remove SAML by selecting a different identity provider. It does not warn that doing so discards the organization's SAML identities, its SAML member roster, and its SCIM access token — meaning SCIM must be reconfigured with a newly issued token and users re-provisioned if you switch back. Given the SCIM docs are otherwise thorough, this deserves a warning note on both pages.
F. Converting an organization to SAML can fail for the admin doing it
The SAML setup guides walk the reader to Membership Requirements → Change requirements and stop. The change is rejected if the admin performing it belongs to other, unrelated Pulumi organizations. This produces a confusing error at the last step of an otherwise well-documented setup flow, and should be listed as a prerequisite.
G. Terminology is inconsistent across surfaces
The docs say "identity provider" and "Membership Requirements"; the console uses both that phrasing and "organization backend"; the API calls it the organization backend. For Bitbucket specifically, the docs and console alternate between "Bitbucket" and "Atlassian" (the connect control is labeled Connect Atlassian, and a linked identity appears as Atlassian) without ever stating they're the same thing. A short glossary note, or simply saying "Atlassian (Bitbucket)" on first use, would help.