Update access tokens docs to reflect RBAC permission model#18102
Update access tokens docs to reflect RBAC permission model#18102
Conversation
Replace the outdated static permissions matrix and fixed member/admin binary model with accurate descriptions of how token permissions are now driven by RBAC role assignments. Clarifies that stack creation depends on org-wide access settings or the token's assigned role rather than being universally available. Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
Docs ReviewFile reviewed: content/docs/administration/access-identity/access-tokens.md This is a solid rewrite that replaces an outdated static permissions matrix with prose explanations tied to the RBAC model. The content is clearer and more accurate. A few issues to address: Issues:
Minor:
What looks good:
Mention me (@claude) if you would like additional reviews or want me to help fix any of these issues. |
There was a problem hiding this comment.
Pull request overview
Updates the Pulumi Cloud access tokens documentation to reflect the current RBAC-based permission model (roles/scopes and org-wide access toggles), replacing the legacy member/admin permission matrix and restructuring org/team token guidance around effective permissions and management.
Changes:
- Replaces the static token-permissions matrix with RBAC-based prose explaining how permissions are derived for each token type.
- Corrects stack-creation guidance to depend on org-wide access settings or RBAC scopes (rather than “all tokens can create stacks”).
- Reworks organization/team token sections to focus on capabilities, audit logging, and who can manage tokens; frames admin org tokens as legacy.
|
Your site preview for commit f6cf0d9 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-18102-f6cf0d98.s3-website.us-west-2.amazonaws.com. |
- Fix ambiguous "Admin tokens" → "Admin organization tokens" in the
stack creation security note
- Remove duplicate admin org tokens subsection from the permissions
overview; replace with a cross-reference to the operational section
- Remove orphaned audit log sentence (already covered per token section)
- Add {#creating-an-organization-access-token} anchor to preserve
existing inbound links from other docs pages
- Add "Legacy organization token types" section explaining the pre-RBAC
admin/standard token distinction and how each maps to the current
built-in Admin and Member roles
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
|
@claude the lint is failing, please fix. |
Co-authored-by: Cam Soper <[email protected]>
Consolidate all admin/standard legacy token content into the "Legacy organization token types" section, including the caution warning and least-privilege guidance. Remove the now-redundant subsection under "Organization access tokens". Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
|
Your site preview for commit 567abe6 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-18102-567abe69.s3-website.us-west-2.amazonaws.com. |
jkodroff
left a comment
jkodroff
left a comment
There was a problem hiding this comment.
Commenting to avoid annoying "request changes". Happy to re-review.
| Organization tokens act on behalf of the organization itself. Rather than mapping to a fixed set of capabilities, organization tokens derive their permissions from the [RBAC role](/docs/administration/access-identity/rbac/roles/) assigned to them at creation time. This means you can tailor the exact level of access an organization token has—from read-only access to a subset of stacks, to full administrative control—by assigning the appropriate role. | ||
|
|
||
| Organization tokens that are assigned no explicit role receive the organization's [default member role](/docs/administration/access-identity/rbac/roles/). The token's access is automatically limited to the single organization it was created in, unlike a personal token which spans all of a user's organizations. |
There was a problem hiding this comment.
| Organization tokens act on behalf of the organization itself. Rather than mapping to a fixed set of capabilities, organization tokens derive their permissions from the [RBAC role](/docs/administration/access-identity/rbac/roles/) assigned to them at creation time. This means you can tailor the exact level of access an organization token has—from read-only access to a subset of stacks, to full administrative control—by assigning the appropriate role. | |
| Organization tokens that are assigned no explicit role receive the organization's [default member role](/docs/administration/access-identity/rbac/roles/). The token's access is automatically limited to the single organization it was created in, unlike a personal token which spans all of a user's organizations. | |
| Organization tokens are scoped to a Pulumi Cloud organization. Organization tokens derive their permissions from the [RBAC role](/docs/administration/access-identity/rbac/roles/) assigned to them at creation time, or the organization's default member role if no role is specified. |
There was a problem hiding this comment.
We need to link to the default member role, but I don't think we've actually defined what this is or how it works.
Co-authored-by: Josh Kodroff <[email protected]>
Co-authored-by: Josh Kodroff <[email protected]>
Co-authored-by: Josh Kodroff <[email protected]>
|
Your site preview for commit 0974d49 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-18102-0974d49d.s3-website.us-west-2.amazonaws.com. |
|
Your site preview for commit 7fa685d is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-18102-7fa685de.s3-website.us-west-2.amazonaws.com. |
|
Your site preview for commit 1df708f is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-18102-1df708f4.s3-website.us-west-2.amazonaws.com. |
…e syntax Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
CamSoper
left a comment
CamSoper
left a comment
There was a problem hiding this comment.
Looks good — the RBAC rewrite is clear and well-structured. I also pushed a fix for a few pre-existing style issues (heading case, list numbering, shortcode syntax).
@jkodroff's suggestions are worth considering — particularly around clarifying "machine token" terminology, linking to the default member role docs, and being more prescriptive about when to use each token type. Those could be addressed in a follow-up.
|
Your site preview for commit 62d7698 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-18102-62d7698f.s3-website.us-west-2.amazonaws.com. |
Replace "machine tokens owned by the organization" with clearer language about what these tokens actually do: authenticate as the org/team itself and attribute actions in audit logs accordingly. Addresses PR feedback about "machine tokens" being ambiguous and "owned by the organization" being unclear. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Addresses PR feedback asking "For how long?" about token name reservation after deletion. The service enforces permanent uniqueness including soft-deleted tokens to guarantee audit log traceability. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Replaces generic "well-suited for CI/CD" language with concrete use cases (CI/CD, drift detection, policy enforcement, reporting) and recommends org tokens over personal tokens for automation. Steers users toward custom roles for least-privilege access. Addresses PR feedback requesting more prescriptive guidance. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
|
Your site preview for commit 99373a0 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-18102-99373a06.s3-website.us-west-2.amazonaws.com. |
Summary
stack:createRelated issues
Fixes #11590
🤖 Generated with Claude Code
claude --resume 6ffbf5a6-c22c-40e4-839f-93df2afc42cd