docs: rewrite Roles & Permissions as the self-serve RBAC reference - #802
Open
abhijaisrivastava15 wants to merge 50 commits into
Open
docs: rewrite Roles & Permissions as the self-serve RBAC reference#802abhijaisrivastava15 wants to merge 50 commits into
abhijaisrivastava15 wants to merge 50 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.
A customer admin opening this has one job: get their team onto the platform. Everything they needed was already on the page, but nothing told them the order, so they had to assemble the sequence themselves out of six sections. Adds a five-step Set up your team walkthrough at the top, a role table keyed to what a person does rather than what the role is called, an explicit warning that Admin cannot be fenced out of a workspace, and a short table for the question that actually gets asked: someone says they cannot see something, what is it. Everything below stays as the reference they come back to.
Four readers were given nothing but this page and a real job, and told to report every point where they would have to email us. Fixes, in the order they would have hurt: - The recommended team-lead setup could not manage its own engineers. A Workspace Admin only outranks people below them in the ORGANISATION, so the engineers now go in as organisation Viewer with the Workspace Member role, which costs them nothing and lets the lead manage them. Says up front that the org role is rank and the workspace role is ability, which is the model the whole page was missing - A key takes the workspace you have open when you create it, and the dialog neither says so nor offers a field. Verified against the stored keys. Whoever is isolating teams has to know this or their traces land in the wrong place - The trace routing read as a contradiction. Traces follow the key and ignore a workspace header; only other calls can override it - Said what workspaces do NOT separate: the gateway, the key list, and usage. Someone promising a customer isolation needs that before they promise it - Share links have no revoke, no expiry, no regenerate. Said so, and where to go instead - Gateway: the FAQ said no role checks, the body said writes are refused. Reading is what is ungated - Integrations and AI Providers each name two different screens - Both refusals that had a real answer (separate gateway logs, separate bills) now name it: separate organisations - A departing person's API key keeps working, because the key belongs to the organisation. Added to the removal steps - New closing section for the three things with no self-serve answer - Dropped the claim that a workspace-less person is auto-added on first sign-in, which was never observable in the product
Proved in both directions on a two-workspace organization. A key created inside one workspace is stored against it, and the Keys page of the other workspace does not list it at all, it shows the empty state instead. So the earlier line claiming one org-wide key list was wrong, and the real risk is the opposite one: make a key in the wrong workspace and you cannot find it again until you switch back. The starter system_org_key carries no workspace and shows up in the default one. What genuinely does cross the boundary is where a key can SEND, which is the whole organization, so that is what the isolation table now says.
Two rounds of adversarial readers were run against the fixed page. One got all the way through the full setup job without stopping. These are what the second round still caught: - A team lead's invite carries no organisation role field, so the lead cannot set anyone's rank and cannot fix it afterwards either. The recommended model quietly broke the first time a lead onboarded their own hire. Says so, and says to check Members after they do - Dropped the implication that a removed person can be reinstated. The dashboard offers no undo, so that now sits in the cannot-help table with the other two documented limits rather than being hinted at - Said what a key can be AIMED at, not just where it can send: traces are fixed to the key's workspace, other calls can name a different one in the same organisation. Anyone writing an isolation memo needs it - The gateway refusal no longer implies a mechanism that was never observed, it just says who it stops - A workspace can be renamed from its General tab, which nothing said
Anyone who lands on the API keys page directly hits the same trap: the dialog asks for a name and nothing else, but the key takes whichever workspace is open and the list only shows that workspace's keys. Adds the warning, a step telling you to check the switcher first, and the line about sending both values on if the key is for somebody else.
…I Providers The workspace-role table said no while the tab table two sections up said yes. The tab table is the one that matches what the seats actually see: Workspace Member gets General, Integrations and AI Providers, and it is the Members tab that needs Workspace Admin. Split the row so both agree.
It is the model the whole page turns on and the one thing that stops an admin building a team their own lead cannot manage, so it should be the first thing read rather than a note halfway down.
Anyone jumping straight to the API keys card to check what their key can do read 'one organization, and one workspace inside it' and stopped there, which contradicts the page's own rule that non-trace calls can name any workspace in the organization. That reader either provisions a key they do not need or raises the exact ticket the rule was added to prevent, so the card now carries the whole answer. Also: the cannot-help list said three and had four rows, and the audit question was bundled under a line implying our team can retrieve one. It cannot be answered from this page either way, so it now sits on its own and says to ask before promising a compliance reviewer anything.
…es only Someone doing an isolation review lands on this page, reads that a key belongs to the workspace it was made in, and concludes the key is the boundary. It is not: other calls can name a different workspace in the same organization. Same correction the permissions page just took.
It cannot. An Observe project can be set to Restricted; a dataset link is always open to whoever holds the URL. The FAQ answered for both at once, so somebody reading only the FAQ would go looking for a control that does not exist, or worse, believe a dataset link was private when it is not. That is the same failure as the API key card, on a security question. Also named the one key that has no workspace, the starter system_org_key, instead of leaving a hanging clause about keys that have none.
Same failure as the last two, found by reading every FAQ answer against the section it summarises rather than waiting to be told again. - The blocked-page answer listed two outcomes where the body lists three, and the missing one is the dangerous one: the page opens normally and the buttons do nothing - 'My SDK data is going to the wrong place' answered only at the organization level. Somebody whose traces are in the wrong WORKSPACE was being told to check the organization. Split by which half is wrong
The rank caveat lived in a note under one of the two tables, so a reader who only looked at either table got a flat Yes and built a team their lead could not manage. Both cells now carry it.
It said Integrations and AI Providers need Workspace Admin. A Workspace Member gets both. Same correction the permissions page took, split per role so the table answers on its own instead of needing the prose.
…is not The starter system_org_key was never created in one. Scoping the card to a key you create leaves both statements true without an edge case the reader has to reconcile.
It answered on roles only. The commonest real cause is that the Keys page lists just the current workspace's keys, so somebody who genuinely has access and genuinely made a key still sees an empty page. Both causes now, cheapest check first.
…page itself disproves The scoping card exists to answer 'can a teammate in another workspace see this', and it listed platform API keys as organization-wide. The walkthrough and the keys reference both say the opposite: the list only ever shows the workspace you have open. A security reviewer trusting the card gets the wrong answer on a credential. Keys genuinely sit across that line, so they come out of the either/or and get said properly: the LIST is per workspace, what the credential can REACH is the organization. Also from the same read: - The organization-role summary scored Member and Viewer identically on every row, erasing the one difference the page argues for elsewhere. Added the AI Providers row - The Owner card named 'transfer ownership' with no path anywhere on the page. Names the promote-then-demote one - Three descriptions of the invite dialog gave two different field orders - Dropped the unobserved claim about re-inviting an existing member at a lower role, and pointed at Edit user info instead
Three gates read the page at once. All three failed it, and the sharpest findings were sentences I had written to fix earlier findings. - The section on what each role sees OPENED by saying the sidebar and Settings are identical in every workspace, then two subsections later listed Build > Keys, Invite members and the workspace tabs as things that change when you switch. Somebody watching their own nav change would read the product as broken. Split by what follows which role - The troubleshooting row promised every action greyed out for a Workspace Viewer. Gateway is exactly the page where that is false - system_org_key was 'the one exception' in one place and 'works like any other key' in another, on the single property anyone cares about - The FAQ a confused person actually opens never mentioned that exception - Offboarding said to open Build > Keys once, on a page that only ever shows one workspace, and to 'disable or delete' when delete is Owner-only - The workspace-role table had no gateway row while gateway writes are gated on exactly the permission that table tracks - The no-revoke warning opened broadly and was only ever proved for datasets. Scoped to what was proved, honest about the Observe case
Two readers stopped at the same place: can you take back an Observe share you already sent. I had written that the page could not promise either way, which is not an answer. Opened the dialog. An Observe project shares a separate /shared/ link, not the project's own address, and the dialog reopens with the current setting, so setting it back to Restricted is the control. A dataset has none of that: its link is the dataset's own address and Done is final. Both now say which is which, including the cannot-help row.
…rred One invite carries one organization role, one workspace role and one set of workspaces, and every address in it gets all three. A reader working through the setup inferred that from the order of the paragraph and flagged that it is easy to assume you can hand different people different workspaces in one send.
The mechanical sweep closed all seven prior items and found no count or reference errors. What it did catch: - Default Workspace was the one workspace told 'you cannot delete it' with no route out, while every other one is sent to the Future AGI team - The Admin card never mentioned billing, so a customer picking who gets billing access would read the Owner card as the only option. Admin has the same controls - The scoping section is sold as the full list and left out the Settings pages for AI Providers, Integrations and Falcon AI Connectors. Added, with the reason those two names appear on both sides
Fixed it at the top of the section it governs and left the same sentence standing further down. Build > Keys follows the workspace role, so the sidebar does change, and a customer watching it change reads that as a fault. Found by re-reading my own edits rather than by a reviewer.
Two card-level clashes, both introduced by earlier fixes on this branch. The Member card said 'cannot open organization settings' flat, while the Settings table and the permission summary both give Member the org-level AI Providers page. Somebody choosing Member specifically to keep a person away from provider configuration would have got it wrong. And the workspace card listed Integration connections but not AI Provider connections, immediately under a sentence saying both names appear on both sides.
My own previous fix was still imprecise: it gave Member AI Providers and implied nothing else, when Member also has Profile and Usage Summary. And the Viewer card carried the same flat 'cannot open organization settings' line, which is wrong for the same reason. Both cards now list exactly the rows the Settings table gives them.
The body says one of the three things you get is the page itself, with buttons that do nothing. So it may well 'help' in the sense of loading, which is the confusing case. Row now matches the warning it summarises.
…ad one Invite members only appears while they are standing in a workspace they administer. Once the dialog is open the picker offers every workspace they belong to, which is what the seat actually showed when it was driven. An owner reading only the table would have got the reach wrong in one direction, and the suggested single-clause fix would have got it wrong in the other, so both halves are stated. Also: bare 'templates' in the workspace card read as covering Future AGI's built-ins, which live everywhere, and the switcher note counted three jobs while the step two paragraphs above uses it for a fourth.
It was three, then four, and opening Settings makes it five. The count is not the point and it keeps going stale, so the note just lists what the control does.
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 page a customer can set their own team up from, and aligns the sibling pages that contradicted it.It now opens with the job rather than the taxonomy: a five-step Set up your team walkthrough, a role table keyed to what a person does rather than what the role is called, what the workspace boundary does and does not cover, and the short table for the question that actually gets asked, which is someone saying they cannot see something. Everything below that is the reference they come back to.
Why
This page has been through three passes on this branch.
Pass one derived every claim from the source. Pass two threw that out and re-derived the page from the running product, because a customer cannot read our source, driving nine role combinations through the live dashboard and keeping only what could be reached by clicking.
Pass three, in this update, stopped checking whether the page was true and started checking whether it was usable. Four readers were each given nothing but this page and a real job, and told to report every point where they would have to email us. Two more verified the fixes. Every finding below came from one of them.
What the readers changed
The recommended setup could not do its own job. The page told you to make a team lead an organization Member and a Workspace Admin, and separately told you a Workspace Admin can only manage people ranked below them in the organization. Both true, and together they meant the lead could not remove the engineers the same page told you to hire as Members.
The page now says up front that the organization role is rank and the workspace role is ability, puts the engineers in as organization Viewers with the Workspace Member role, which costs them almost nothing, and names the one thing it does cost. It also warns that a team lead's own invite carries no organization role field, so the ranking has to be checked after a lead onboards someone.
A key silently takes the workspace you have open. The Add API Key dialog asks for a name and nothing else and never mentions a workspace, but the key is bound to whichever workspace is active and traces sent with it land there. Verified against the stored keys.
The Keys page is scoped to that workspace too. Proved in both directions on a two-workspace organization: a key made in one workspace does not appear in the other's list at all, which shows the empty state instead. The earlier revision claimed one organization-wide key list. That was wrong, and the real risk is the opposite one, which is making a key somewhere you will not find it again.
Said what the workspace boundary does not cover. The gateway, where every role can read every team's request logs. Usage Summary, which is open to everyone. And what a key can be aimed at, since traces are fixed to the key's workspace but other calls can name a different one in the same organization. Anyone promising a customer isolation needs all three before they promise it.
Share links, precisely. A dataset shares its own address with one mode and no way back: the dialog is a link, a copy button, Cancel and Done. An Observe project shares a separate
/shared/link and its dialog reopens, so setting it back to Restricted is the one control you have over a link already sent. Two readers stopped at exactly this question, so it got opened and answered rather than hedged.Both refusals that had a real answer now name it. Separate gateway logs and separate bills both mean separate organizations, which the page already established share nothing.
A departing person's API key keeps working, because the key belongs to the organization rather than to them. Added to the removal steps with the column to check.
Also fixed: the gateway FAQ said there were no role checks while the body described an enforced one;
IntegrationsandAI Providerseach name two different screens; the per-workspace tab set was wrong for a Workspace Member; and the claim that a workspace-less person is auto-added on first sign-in was dropped, because it was never observable in the product.What the page now admits it cannot do
A new closing section, because a documented limit is cheaper than a support ticket:
All four route to the Future AGI team, and everything else on the page an Owner or Admin can already do themselves.
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, Workspaces is singular/settings/workspace. The previously documented/settings/profile,/settings/organizationand/settings/workspacesare not routes and 404 for an Owner.The failure this page kept making
Every blocker the readers found was the same shape: a card, a table row, or an FAQ answer that reads fine on its own and contradicts the detailed section elsewhere. Somebody looking one thing up reads it and stops.
Some of what that produced: a key card saying a key is capped to one workspace when non-trace calls can target any workspace in the organization; the scoping card filing platform API keys under the organization when the Keys page only ever lists the workspace you have open; a sharing FAQ implying a dataset link can be restricted to named people when it is always public; a blocked-page answer listing two failure modes where the body lists three, missing the one where the page opens and the buttons silently do nothing; a section that opened by saying the navigation is identical in every workspace and then listed three things that are not; and both workspace-role tables reporting "manage members" as a flat Yes with the organization-rank caveat sitting only in a note under one of them.
The later rounds were mostly catching sentences written to fix earlier rounds, which is the real hazard here and the reason the reviews kept going until a full sweep came back clean.
Where the reviews landed
The last sweep graded every finding by severity and returned SHIP: nothing that blocks a customer task, nothing that would cost them access, data or a credential if skimmed, and one loose count that has since been removed. A separate reader working the full setup job returned SHIP the round before, with no blockers at all.
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
0-0 of 0everywhere. Untestable, so unclaimed.