docs: rewrite Roles & Permissions as the self-serve RBAC reference - #802
Open
abhijaisrivastava15 wants to merge 23 commits into
Open
docs: rewrite Roles & Permissions as the self-serve RBAC reference#802abhijaisrivastava15 wants to merge 23 commits into
abhijaisrivastava15 wants to merge 23 commits into
Conversation
Covers organization and workspace roles, annotation queue roles, what is scoped where, share links, API keys, invites, member changes, two-factor enforcement, and seats. Adds a hand-authored access-levels diagram and converts the inherited screenshots from blur to the house mask style.
…2FA location, and sharing claims Regrounded every claim against origin/dev 2bf0d79b7. Corrects 17 statements the code contradicts and 34 that overstated or understated real behaviour.
Second verification pass found 13 of the replacement sentences were also wrong. Corrects the workspace-admin billing/keys leak, the org switcher, the workspace fallback chain, MCP scoping, system key deletion, the real UI page names, and the SAML cutover behaviour.
…lt text Screenshots now sit under public/images/docs/rbac/ alongside the diagram, per WRITING_DOCS. Replaces terse markdown alt with descriptive sentences. Drops workspace-members.png, orphaned by the rewrite.
The roles page is the authority on who can reach what. These pages contradicted it on API key access, billing access, the 2FA grace period, and what removing a member does, and several printed API enum strings or settings-page names that do not match the product sidebar.
Replaces essayistic and meta phrasing with plain statements of fact, to match the rest of the docs. No claim changed.
Unstacks negations, splits compound conditionals, and replaces qualifier chains like 'a Reviewer who is not also an Annotator'. No claim changed.
…arkup Adds inline links on first mention, italic captions under every image, and the centring wrapper the other diagrams use. Fixes a dropped subject and a duplicated line.
Verified against the live product, not the route table. Platform keys live at Build > Keys in the left sidebar; the only thing named API Keys is the gateway's. Corrects every path, label and role gate that got this wrong, repoints 35 cookbook links at the real API keys page, and removes the admin-settings.mdx file that collided with admin-settings/index.mdx on /docs/admin-settings.
Checked against the live product. The invite button is Invite User, the workspace button is Create New Workspace, and Org Settings exposes a single Require 2FA for all members toggle with no grace-period field, so the doc no longer promises one.
Logged into the product and opened the invite modal and the create-queue drawer. One workspace role applies to all selected workspaces, not one per workspace. Auto-assign is a checkbox on the queue. Queue roles are three independent checkboxes and the creator gets all three. Owners can transfer ownership. The queue form's button is Create annotation queue.
…gs.mdx The route still resolves from admin-settings/index.mdx, so the entry never fires, but the deleted-page check requires one.
jedigalt
requested changes
Aug 12, 2026
There was a problem hiding this comment.
We dont have seat limits, we dont have gateway keys and request logs as part of organization
There was a problem hiding this comment.
Why are we not having traces as lever for data? Also, why is that default and team a and team b is different? doesnt make sense
|
|
||
| <Steps> | ||
| <Step title="Open Settings"> | ||
| Navigate to **Settings > API Keys** at [https://app.futureagi.com/dashboard/settings/api_keys](https://app.futureagi.com/dashboard/settings/api_keys). |
There was a problem hiding this comment.
bhai did you even read or check UI for this? WTF is wrong with you? where do we have settings and API keys?
| *Granting Admin or Owner hides the workspace picker, because those roles reach every workspace.* | ||
|
|
||
| ### Invitation rules | ||
| An invite is valid for 7 days. After that it shows as Expired and has to be resent, which restarts the 7 days. An invite that has not been accepted can also be cancelled, which takes it off the list. |
There was a problem hiding this comment.
I think invite is valid for 24 hours only please verify the email link expires
| - You can only invite users at a role **equal to or below** your own role. An Admin cannot invite an Owner. | ||
| - **Workspace Admins** can invite users but only grant access to workspaces they manage. | ||
| - If an invite is not accepted within 7 days, it expires. You can resend it from the members list. | ||
| Inviting an address that already belongs to an active member does not create a second invite. It adds that person to the workspaces you selected, and raises their organization role if you picked a higher one. |
| | Usage Summary | Everyone | | ||
| | Profile | Everyone | | ||
| | AI Providers, Integrations, and Falcon AI Connectors | Owner, Admin, Member, Workspace Admin, Workspace Member | | ||
| | MCP Server | Owner, Admin | |
There was a problem hiding this comment.
if this is not there for members we need to add this
| --- | ||
| Billing, Plans & Pricing, and Usage Summary are Future AGI Cloud only. They are not part of a self-hosted deployment. | ||
|
|
||
| Seats are counted across the whole organization, not per workspace, and your plan sets how many are included. Adding a workspace never adds capacity. Going past the included count does not block an invite. The extra seats are billed as overage. |
|
|
||
| ## Organization security | ||
|
|
||
| Owners and Admins can require two-factor authentication across the whole organization, from [**Settings > Org Settings**](/docs/admin-settings/organization-settings). |
There was a problem hiding this comment.
can require 2-factor english isnt comprehensible
…eenshots Seats are not a product concept; the word appears nowhere in the platform, so the section, the FAQs, the scope list and the diagram label are gone. Members page rebuilt into invite / edit / remove, and covers the second invite path from the workspace switcher. Usage Summary rewritten from what the page actually meters. Screenshots recaptured at 3024px and masked to the house convention.
…shot The black mask blocks sat on top of the dialog text. The invite screenshot is now cropped to the dialog itself, so there is nothing to redact, and the members list uses a blur over the email column instead.
…ed workspace deletion claims
Backend gates delete_secret_key on RolePermissions.OWNER_ROLES = [OWNER]. Admins and Workspace Admins see the Delete Key action but the server rejects it.
Every claim on these four pages was re-verified by driving the live dashboard as nine different role combinations, rather than read off the code. Corrections: - Keys is Owner and Admin only. Workspace Admins do not get it - Settings is a grouped tree, not a flat list of pages - Add a role-by-role table of which Settings pages actually appear - Warn that an unreachable page either 404s or silently returns you to Datasets, so a customer can tell a permission block from a bug - Share options are Anyone with the link and Restricted. Datasets only offer the first - Both the API key and the secret stay masked, so name the copy button - Add Disable Key and Re-enable key, and lead rotation with disable - Say plainly that a workspace cannot be deleted from the dashboard - Use the product's own role wording and its own error strings - Drop the sign-in-method nuance: the last organization and workspace are remembered on the account regardless
Reversing the previous commit on this point. A clean Workspace Admin, meaning an organization Member holding workspace_admin, gets Keys in the sidebar, the page loads, and Add API Key, Disable Key and Delete Key are all live. The seat that 404'd stores its workspace role as a value the route gate does not recognise, so it was never the general case. Also from the same pass: - A Workspace Admin has no organization Members entry. They reach their workspace's member list through Your Workspaces or Workspace settings - Managing workspace members still respects the organization ranking, so a Workspace Admin can only act on people below their own org role - A page reached by typing its address may render and still not work, so say that alongside the 404 and the silent bounce
Proved by a controlled A/B: same key, same org, same clicks, only the signed-in role changed. The Admin gets 'You are not authorized to access this resource' and the key survives. The Owner gets 'has been deleted' and it goes. The button is shown to everyone who can open the page, so it fails at the confirmation rather than being hidden, and the doc now warns about exactly that. - AI Providers follows the organization role, not the workspace role. It is there for Member and above and absent for Viewer - The workspace role wins in both directions. An organization Member added as Workspace Viewer cannot create, edit, or share - The gateway is readable by every role, but a create is refused on submit with 'Write access denied to this workspace'. It leaves its buttons enabled where the rest of the product greys them out
A Workspace Admin and a Member see exactly the same Settings tree, so a Workspace Admin column in that table implied a difference that is not there. Dropped it, and said plainly which two things the workspace role does change: Build > Keys, and Invite members in the switcher.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Rewrites
Roles & Permissionsinto the self-serve RBAC reference, and aligns the sibling pages that contradicted it.Covers the organization/workspace split, all four organization roles and three workspace roles, what each role actually sees on screen, annotation queue roles, multi-org membership, what is scoped to a workspace vs the organization, share links, both kinds of API key, invites, role changes and removal, billing, and the two-factor policy. Ends with two permission tables and an FAQ.
Why
The page that existed described a system the product does not implement.
This branch has been through two passes. The first derived every claim from the source on
future-agi/future-agi@origin/dev. The second, in this update, threw that out and re-derived the whole page from the running product, because the page is going to a customer and a customer cannot read our source. Anything that could not be reached by clicking is gone.Method: eleven role combinations were driven through the live dashboard in a headless browser, one persona per seat, clicking the real UI rather than calling endpoints.
Two of the orgs used have six workspaces, which is what made the cross-workspace half of the page testable at all.
What the clicking changed
Delete Key is Owner only, and the button lies. Everyone who can open the Keys page sees Delete Key, gets the confirmation, and then an Admin or Workspace Admin is told You are not authorized to access this resource while the key stays in the list. Proved with a controlled A/B: same key, same organization, same coordinates, only the signed-in role changed. The page now warns about it and tells you to disable instead.
Settings is a grouped tree, not the flat list of eleven pages the page printed. It follows the organization role alone, so a Workspace Admin and a Member see an identical Settings tree. The old page's "Workspace Admin reaches Billing and Plans & Pricing" line was wrong at the level that matters: neither is in their navigation. There is now a role-by-role table of what actually appears.
Workspace Admins do reach Build > Keys, and can add and disable. One seat 404'd there during testing and briefly overturned this, but that seat stores its workspace role as a legacy value the route gate does not match. The clean case works. Reversed and re-reversed on evidence rather than left as the first reading.
A page you cannot use fails in three different ways. A 404 with a joke line, a silent return to Datasets with no message at all, or occasionally the page itself with buttons that do nothing for you. The page now tells customers to go by their left navigation and not to read any of the three as a missing feature. This is the single most support-ticket-shaped thing on the page.
Sharing. The options are Anyone with the link and Restricted, not "Only specific people". Datasets only offer the first. Observe projects offer both plus an invite-by-email field. A Workspace Viewer's Share button is greyed out, which the page claimed and is now proved.
API keys are never shown in cleartext. Both the key and the secret stay masked and are taken with the copy button. "The Secret Key is only shown once" was describing something the UI does not do.
A workspace cannot be deleted from the dashboard. Not from the workspace list, not from a workspace's own General page. Said plainly instead of left as an absence.
The workspace role wins in both directions. An organization Viewer added as Workspace Member can create, edit and share. An organization Member added as Workspace Viewer cannot, and every action on a dataset comes back disabled. Both halves tested by actually attempting the write.
The gateway is readable by every role, including a Viewer, and it leaves its create buttons enabled where the rest of the product greys them out. A write is refused at submit with Write access denied to this workspace. The previous description said gateway request logs are invisible outside the default workspace; that could not be reproduced and the claim is gone rather than kept on trust.
Corrections also went into the wording itself: the four role descriptions, the two disabled-menu tooltips, the demotion helper text, the duplicate-workspace error, and the 2FA prerequisite are now quoted from the product rather than paraphrased, so the page and the screen say the same words.
Sibling pages
api-keys,user-management,workspace-managementandfaqwere rewritten against the same evidence. Route names were corrected throughout: Profile is/settings/profile-settings, Org Settings is/settings/org-settings, and Workspaces is singular/settings/workspace. The previously documented/settings/profile,/settings/organizationand/settings/workspacesare not routes and 404 for an Owner.Verification
node scripts/audit-links.mjs: 0 broken content links, 0 broken nav linksnpx astro build: 1029 pages built, no errorsKnown gaps, deliberately left out
/dashboard/gateway/logsreads0-0 of 0everywhere. Untestable, so unclaimed.