diff --git a/public/images/docs/rbac/access-levels.svg b/public/images/docs/rbac/access-levels.svg
new file mode 100644
index 00000000..24c98a43
--- /dev/null
+++ b/public/images/docs/rbac/access-levels.svg
@@ -0,0 +1,50 @@
+
diff --git a/public/images/docs/rbac/invite-modal.png b/public/images/docs/rbac/invite-modal.png
new file mode 100644
index 00000000..0bd15b33
Binary files /dev/null and b/public/images/docs/rbac/invite-modal.png differ
diff --git a/public/images/docs/rbac/users-list.png b/public/images/docs/rbac/users-list.png
new file mode 100644
index 00000000..ff9ee8fd
Binary files /dev/null and b/public/images/docs/rbac/users-list.png differ
diff --git a/src/lib/navigation.ts b/src/lib/navigation.ts
index cb194fd9..9f6bdd7e 100644
--- a/src/lib/navigation.ts
+++ b/src/lib/navigation.ts
@@ -790,7 +790,14 @@ export const tabNavigation: NavTab[] = [
{ title: 'Usage Summary', href: '/docs/admin-settings/usage-summary' },
]
},
- { title: 'Roles & Permissions', href: '/docs/roles-and-permissions' },
+ {
+ title: 'Roles & Permissions',
+ items: [
+ { title: 'Overview', href: '/docs/roles-and-permissions' },
+ { title: 'Manage access', href: '/docs/roles-and-permissions/guides/manage-access' },
+ { title: 'Permission reference', href: '/docs/roles-and-permissions/reference/permissions' },
+ ]
+ },
{
title: 'Billing',
items: [
diff --git a/src/pages/docs/admin-settings/api-keys.mdx b/src/pages/docs/admin-settings/api-keys.mdx
index 9c609b73..25e389a9 100644
--- a/src/pages/docs/admin-settings/api-keys.mdx
+++ b/src/pages/docs/admin-settings/api-keys.mdx
@@ -1,60 +1,84 @@
---
-title: "API Keys: Create & Manage Credentials"
-description: "Create, copy, and rotate FI_API_KEY and FI_SECRET_KEY credentials for authenticating with Future AGI Python and TypeScript SDKs."
+title: "API Keys"
+description: "Creating and rotating the key and secret your SDK authenticates with"
---
-## About
+API keys authenticate your application with Future AGI. A pair is an API Key (`FI_API_KEY`) and a Secret Key (`FI_SECRET_KEY`), and you need one for every way into the platform: the Python and TypeScript SDKs, the Java and C# SDKs, any OpenTelemetry based instrumentation, and the REST API.
-API keys authenticate your application with Future AGI. Each key pair consists of an API Key (`FI_API_KEY`) and a Secret Key (`FI_SECRET_KEY`). You need these to use the Python SDK, TypeScript SDK, or REST API.
+Owners, Admins and Workspace Admins can open this page. For everyone else it is not in the sidebar and its address returns a 404. See [Roles & Permissions](/docs/roles-and-permissions).
-Access: **Owner** only.
+Every organization is created with one key already in the list, named `system_org_key`.
-## How to
+
+**A key belongs to the workspace you have open when you create it.** Traces sent with it land there, and **Build > Keys** only ever lists the keys of your current workspace. The dialog says none of this and offers no workspace to pick, so switch to the workspace you want the key for before you create it.
+
+If the page says *No keys has been added yet* and you know you made one, you are standing in a different workspace. Switch and look again.
+
+
+That binding holds for traces and nothing else. Other API and SDK calls made with the same key can name a different workspace on the request, and you get it as long as that workspace is in the same organization and you have access to it. If you are separating teams, the key's workspace is not what keeps them apart.
+
+## Create a key
-
- Navigate to **Settings > API Keys** at [https://app.futureagi.com/dashboard/settings/api_keys](https://app.futureagi.com/dashboard/settings/api_keys).
+
+ In the left sidebar, find the **Build** section and click **Keys**, or go straight to [https://app.futureagi.com/dashboard/keys](https://app.futureagi.com/dashboard/keys).
+
+
+ The switcher at the top of the sidebar shows it. The key you are about to make belongs to whichever workspace that is.
- Click **Add API Key**. Enter a name for the key.
+ Click **Add API Key**. The dialog asks for a name and nothing else.
- Copy both the API Key and Secret Key. The Secret Key is only shown once at creation time.
+ You are shown an API Key and a Secret Key. Both stay masked on screen, so take each one with its copy button and store it before you close the dialog. This dialog does not come back, and there is no way to reveal a secret later. If you are creating the key for somebody else, send them both values now.
Set them as environment variables.
- ```python
+
+ ```python Python
import os
os.environ["FI_API_KEY"] = "YOUR_API_KEY"
os.environ["FI_SECRET_KEY"] = "YOUR_SECRET_KEY"
```
- ```typescript
+ ```typescript TypeScript
process.env.FI_API_KEY = "YOUR_API_KEY";
process.env.FI_SECRET_KEY = "YOUR_SECRET_KEY";
```
+
-## Managing Keys
+## Managing keys
-| Action | How |
-|--------|-----|
-| View keys | API Key is visible in the table. Secret Key is masked. |
-| Copy a key | Click the copy icon next to the key. |
-| Delete a key | Click the delete icon. This is permanent and cannot be undone. |
-| Rotate keys | Delete the old key and create a new one. Update your application with the new credentials. |
+The table lists each key with its name, a masked API Key and Secret Key, who created it, and when. Every row carries a menu with two actions, and both ask you to confirm first.
+
+**Disable Key** turns off the API Key and the Secret Key together. The row gains a **Disabled** badge, the menu changes to **Re-enable key**, and Owners, Admins and Workspace Admins can all do it.
+
+**Delete Key** removes the API Key and the Secret Key permanently. It cannot be undone, and only an Owner can do it.
-Deleting a key immediately revokes access for any application using it. Make sure to update your code before deleting.
+**Delete Key** appears for everyone who can open this page, but only an Owner's goes through. An Admin or a Workspace Admin gets the confirmation and then **You are not authorized to access this resource**, and the key stays in the list.
-Never commit API keys to version control. Use environment variables or a secret manager.
+**To rotate a key:** create the replacement, update your application, then **disable** the old key rather than deleting it. If something you forgot about was still using it, re-enable takes one click, and disabling is the part you can do yourself without being an Owner.
+
+Both actions take effect at once, so nothing gets a grace period. And never commit a key to version control: use environment variables or a secret manager.
-## Next Steps
+## Gateway keys are separate
+
+The keys on this page are platform API keys. The Agent Command Center has its own keys under **Gateway > API Keys**, and those are reachable by anyone in the organization.
+
+## Dive deeper
-- [SDK & API](/docs/sdk)
-- [Roles & Permissions](/docs/roles-and-permissions)
+
+
+ Install the SDK and send your first call with these keys
+
+
+ Who can reach the Keys page, and what each role can do there
+
+
diff --git a/src/pages/docs/admin-settings/user-management.mdx b/src/pages/docs/admin-settings/user-management.mdx
index f2cdcea9..24ae3832 100644
--- a/src/pages/docs/admin-settings/user-management.mdx
+++ b/src/pages/docs/admin-settings/user-management.mdx
@@ -1,57 +1,98 @@
---
-title: "User Management: Invite & Assign Roles"
-description: "Invite team members, assign Owner, Admin, Member, or Viewer roles, manage workspace access, and deactivate users in Future AGI."
+title: "User Management"
+description: "Adding people to your organization and setting what they can reach"
---
-## About
+The Members page is where you add people to your organization, change what they can reach, and remove access. For what each role can do once they are in, see [Roles & Permissions](/docs/roles-and-permissions).
-User Management lets you invite people to your organization, assign organization-level roles, manage workspace access, and deactivate or remove members. For details on what each role can do, see [Roles & Permissions](/docs/roles-and-permissions).
+Open it from **Settings > Members**. Every person gets one row, showing their name, organization role, workspaces, email, status, and start date.
-Access: **Owner** and **Admin** only.
+Owners and Admins can open this page. A Workspace Admin cannot, but can still invite people, as described below.
-## How to Invite Users
+## Inviting people
+
+There are two ways in.
+
+**From the Members page.** Click **Invite User** at the top right.
+
+**From the workspace switcher.** Open the switcher at the top of the sidebar and choose **Invite members**. This is the path a Workspace Admin uses, since they cannot open the Members page.
-
- Go to **Settings > User Management**.
+
+ One invite can cover several people at once, as a comma separated list.
-
- Click **Add User** or **Invite**.
+
+ Owner, Admin, Member, or Viewer. The dialog describes each one above the field.
-
- Enter the user's email address.
+
+ Choose one or more workspaces and a single workspace role that applies to all of them. At least one workspace is required.
-
- Select an organization role: Owner, Admin, Member, or Viewer.
-
-
- Optionally assign them to one or more workspaces.
-
-
- Click **Invite**. The user receives an email invitation. Their status shows as "Pending" until they accept.
+
+ Click **Send Invite**.
-## Managing Members
+If you grant **Admin** or **Owner**, both workspace fields disappear and are replaced by *Owner and Admin roles have automatic access to all workspaces.*
+
+
+You can only grant your own role or something below it. An Admin's Organization Role list contains Admin, Member, and Viewer, and no Owner. A Workspace Admin's invite has no Organization Role field at all, so they grant a workspace role only, one of Workspace Admin, Workspace Member, or Workspace Viewer.
+
+
+The new row shows as **Pending** until the person accepts. If the email already belongs to a Future AGI account, they are added immediately and show as **Active**.
+
+A Pending row carries two actions: **Resend the invite** and **Cancel invite**. A cancelled invite comes off the list.
+
+
+Invites expire. The invite itself is valid for 7 days, and the link inside the email stops working sooner than that. If someone says the link is dead, resend the invite from their row rather than waiting for it to lapse.
+
-| Action | How |
-|--------|-----|
-| Search | Use the search bar to find members by name. |
-| Filter by status | Filter to show Active, Pending, or all members. |
-| Filter by role | Filter by Owner, Admin, Member, or Viewer. |
-| Change role | Click the edit action on a member's row. Select a new role. |
-| Remove member | Click the delete action. This revokes all access immediately. |
-| Reactivate | Deactivated users can be reactivated from the member list. |
+## Editing someone's access
-## Workspace Assignment
+Every row carries two actions, **Edit user info** and **Remove from organization**.
-When editing a user, you can assign or remove them from specific workspaces. Workspace-level roles (workspace_admin, workspace_member, workspace_viewer) are set separately from the organization role.
+**Edit user info** holds an Organization Role and a Workspace Role.
+
+| What you can change | Options |
+|---|---|
+| Organization role | Owner, Admin, Member, or Viewer |
+| Workspace role | Workspace Admin, Workspace Member, or Workspace Viewer |
+| Workspaces | Which workspaces they belong to. Appears once you set someone to Member or Viewer |
+
+Setting someone to Member or Viewer adds a required **Workspaces** field, because *Members and Viewers need explicit workspace access.* Any workspace you leave unselected is removed from them.
+
+Promoting someone to **Admin** or **Owner** gives them Workspace Admin everywhere at once, and the workspace fields disappear.
-For a detailed breakdown of what each role can access, see [Roles & Permissions](/docs/roles-and-permissions).
+You can change or remove anyone whose organization role is lower than yours, and an Owner can also change another Owner. Where you cannot, the row's menu is disabled and says why. [Manage access](/docs/roles-and-permissions/guides/manage-access#change-someones-access) covers the rest.
-## Next Steps
+## Removing and reactivating someone
+
+Removing someone from the organization ends their access immediately. Nothing they produced is lost.
+
+A few things are blocked outright:
+
+- You cannot remove yourself
+- You cannot remove or demote the last remaining Owner, so promote a second Owner first
+- You cannot remove anyone from their last workspace
+- You cannot remove an Owner or Admin from a workspace, since they reach every workspace anyway
+
+Reactivating is not something the dashboard offers. A removed person is marked Deactivated and there is no control anywhere that brings them back, so contact the Future AGI team if somebody has to be restored.
+
+## Finding people
+
+Above the table sit a **Search by name or email** box, an **All status** filter, and an **All Roles** filter.
+
+## Dive deeper
-- [Roles & Permissions](/docs/roles-and-permissions)
-- [Organization Settings](/docs/admin-settings/organization-settings)
+
+
+ What each organization and workspace role can reach
+
+
+ Create workspaces and manage who belongs to them
+
+
+ The organization name and its security policy
+
+
diff --git a/src/pages/docs/admin-settings/workspace-management.mdx b/src/pages/docs/admin-settings/workspace-management.mdx
index 071a5efd..0111f12d 100644
--- a/src/pages/docs/admin-settings/workspace-management.mdx
+++ b/src/pages/docs/admin-settings/workspace-management.mdx
@@ -1,45 +1,85 @@
---
-title: "Workspace Management: Projects & Teams"
-description: "Create workspaces to isolate environments and teams, manage workspace members, AI providers, integrations, and usage per workspace."
+title: "Workspace Management"
+description: "Creating workspaces and controlling who can reach the work inside them"
---
-## About
+A workspace holds its own datasets, prompts, members, AI provider configurations, integrations, and usage tracking. None of it is visible from another workspace, so use workspaces to keep production apart from staging, or one team's work apart from another's.
-Workspaces let you organize projects and control access within your organization. Each workspace has its own members, AI provider configurations, integrations, and usage tracking. Use workspaces to separate environments (production vs staging), teams (engineering vs data science), or projects.
+Owners and Admins create workspaces. A Workspace Admin manages the workspaces they administer. See [Roles & Permissions](/docs/roles-and-permissions).
-Access: Owner and Admin at the organization level. Workspace admins can manage their own workspace settings.
+## Creating a workspace
-## Creating a Workspace
+There are two ways in.
-1. Go to **Settings > Workspace**
-2. Click **Create Workspace**
-3. Enter a name for the workspace
-4. Click **Create**
+**From Settings.** Go to **Settings > Workspaces** and click **Create New Workspace**.
-## Workspace Settings
+**From the switcher.** Open the switcher at the top of the sidebar, hover the workspace name, and choose **Create Workspace**.
-Each workspace has its own settings page with these sections:
+Both open the same dialog. Enter a name and click **Create workspace**. You become the admin of the workspace you create.
-| Section | What it controls |
-|---|---|
-| General | Workspace name |
-| Members | Who has access and their workspace-level roles |
-| Integrations | Workspace-specific integration connections |
-| AI Providers | Workspace-specific AI provider configurations |
-| Usage | Workspace-level usage metrics |
+
+Workspace names are unique inside an organization. Reusing one gives you **Workspace with this name already exists**.
+
+
+If **Create Workspace** is not offered in your switcher, your role cannot create one. Ask an Owner or Admin.
+
+## The workspaces list
+
+**Settings > Workspaces** lists every workspace in the organization with its name, admins, start date, and last updated date, and has a search box above the table.
+
+
+There is no way to delete a workspace from the dashboard. Neither this list nor a workspace's own General page offers one. If you need a workspace removed, contact the Future AGI team.
+
+
+## Workspace settings
+
+Open a workspace from **Your Workspaces** in the Settings navigation, or from **Workspace settings** in the switcher. What you get depends on your role in that workspace.
+
+| Tab | What it controls | Workspace Admin | Workspace Member | Workspace Viewer |
+|---|---|---|---|---|
+| General | The workspace name, with a **Save Changes** button | Yes | Yes | Yes, but with no Save |
+| Members | Who has access and their workspace role | Yes | No | No |
+| Integrations | The workspace's own integration connections | Yes | Yes | No |
+| AI Providers | The workspace's own AI provider configurations | Yes | Yes | No |
+
+Owners and Admins get all four in every workspace, since they are Workspace Admins everywhere. A Workspace Viewer gets General alone and cannot save it, so the page is read-only for them.
+
+## Managing workspace members
+
+
+
+ From **Your Workspaces** in the Settings navigation, or **Workspace settings** in the switcher.
+
+
+ The grid lists each person with their name, organization role, workspace role, email, status, and start date.
+
+
+ Add or remove members, and set each one to Workspace Admin, Workspace Member, or Workspace Viewer.
+
+
+
+The actions on a row are **Edit user info** and **Remove from workspace**.
-## Managing Workspace Members
+
+Managing workspace members still follows the organization role, so a Workspace Admin can change or remove only the people whose organization role is lower than their own. [By workspace role](/docs/roles-and-permissions/reference/permissions#by-workspace-role) carries the full grid.
+
-1. Open the workspace settings (click on a workspace from the list)
-2. Go to the **Members** tab
-3. Add or remove members, and set their workspace-level role (`workspace_admin`, `workspace_member`, `workspace_viewer`)
+A Workspace Admin can also invite straight into their workspace with **Invite members** in the switcher. That invite grants a workspace role only, never an organization role.
-Organization-level roles and workspace-level roles are separate. A user can be a "Member" at the org level but a "workspace_admin" in a specific workspace. See [Roles & Permissions](/docs/roles-and-permissions) for how these interact.
+Organization roles and workspace roles are separate. Someone can be an organization Member and a Workspace Admin in one workspace, and an organization Viewer added as a Workspace Member can create and edit there.
-## Next Steps
+## Dive deeper
-- [User Management](/docs/admin-settings/user-management) - Add and manage organization members
-- [AI Providers](/docs/admin-settings/ai-providers) - Configure LLM providers per workspace
-- [Integrations](/docs/admin-settings/integrations) - Connect external tools per workspace
+
+
+ Add and manage the people in your organization
+
+
+ Configure LLM providers per workspace
+
+
+ Connect external tools per workspace
+
+
diff --git a/src/pages/docs/roles-and-permissions.mdx b/src/pages/docs/roles-and-permissions.mdx
deleted file mode 100644
index e9309d9e..00000000
--- a/src/pages/docs/roles-and-permissions.mdx
+++ /dev/null
@@ -1,158 +0,0 @@
----
-title: "Future AGI Roles and Permissions: RBAC Access Control"
-description: "Future AGI provides role-based access control (RBAC) with organization roles (Owner, Admin, Member, Viewer) and workspace roles for team access management."
-icon: "user-shield"
----
-
-Future AGI provides a role-based access control (RBAC) system with two levels: **organization roles** and **workspace roles**. This guide explains what each role can do and how access works across your team.
-
----
-
-## Organization Roles
-
-Every user in your organization has one of four roles. These control what the user can do across the entire organization.
-
-| Role | Description |
-|------|-------------|
-| **Owner** | Full control over the organization. Can manage billing, settings, members, and all workspaces. Every organization must have at least one owner |
-| **Admin** | Same access as Owner, except cannot manage Owners or other Admins. Automatically gets admin access to all workspaces |
-| **Member** | Can view, create, and edit resources in workspaces they belong to. Cannot manage members or organization settings |
-| **Viewer** | Read-only access. Can view data but cannot create, edit, or delete anything |
-
-
-**Owner and Admin users automatically get Workspace Admin access to every workspace** in the organization. You do not need to add them to individual workspaces.
-
-
----
-
-## Workspace Roles
-
-Workspaces let you organize projects, datasets, traces, and queues into separate groups. Users who are not Org Admins or Owners need explicit workspace membership to access a workspace.
-
-| Role | Can View | Can Edit | Can Manage Members |
-|------|----------|----------|--------------------|
-| **Workspace Admin** | Yes | Yes | Yes |
-| **Workspace Member** | Yes | Yes | No |
-| **Workspace Viewer** | Yes | No | No |
-
-You can view workspace members and their roles from the workspace settings page.
-
-
-
-
-### How workspace access is determined
-
-A user's effective workspace access is the **higher** of their organization role and their workspace role:
-
-- An **Org Admin** always has Workspace Admin access everywhere, even without explicit workspace membership
-- An **Org Member** with **Workspace Admin** on a specific workspace gets admin access only in that workspace
-- An **Org Member** with no workspace membership has **no access** to that workspace
-
----
-
-## Inviting Users
-
-Org Admins and Workspace Admins can invite new users to the organization. You can manage all members from the **Organization > Members** page.
-
-
-
-
-
-
- Go to **Organization > Members** in the sidebar.
-
-
- Click the invite button and enter the user's email address.
-
-
- Choose the organization role: Owner, Admin, Member, or Viewer.
-
-
- Select which workspaces the user should have access to and set their workspace role for each.
-
-
- The user receives an email invitation. The invite is valid for 7 days.
-
-
-
-
-
-
-### Invitation rules
-
-- 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.
-
----
-
-## Managing Members
-
-### Changing a user's role
-
-Org Admins and Owners can change any member's organization role or workspace role from the **Users** page.
-
-
-
-
-- You cannot manage a user **at or above your own role** (escalation prevention). Only Owners can manage other Owners.
-- If you promote a user to Admin or Owner, they automatically get Workspace Admin access to all workspaces
-- If you demote an Admin to Member, their workspace access reverts to their explicit workspace memberships
-
-### Removing a user
-
-- Removing a user from the **organization** also removes them from all workspaces
-- Removing a user from a **workspace** only removes workspace access — they stay in the organization
-- You cannot remove the **last Owner** of an organization
-- You cannot remove **yourself**
-
-### Reactivating a user
-
-Previously removed users can be reactivated from the members list. Their original role is preserved.
-
----
-
-## Permission Summary
-
-| Action | Owner | Admin | Member | Viewer |
-|--------|-------|-------|--------|--------|
-| View traces, sessions, datasets | Yes | Yes | Yes | Yes |
-| Create/edit traces, datasets, queues | Yes | Yes | Yes | No |
-| Manage organization settings | Yes | Yes | No | No |
-| Invite and manage members | Yes | Yes | No | No |
-| Manage Owners and Admins | Yes | No | No | No |
-| Access all workspaces automatically | Yes | Yes | No | No |
-| Manage billing | Yes | Yes | No | No |
-| Create/delete workspaces | Yes | Yes | No | No |
-
-| Workspace Action | Workspace Admin | Workspace Member | Workspace Viewer |
-|------------------|-----------------|------------------|------------------|
-| View workspace resources | Yes | Yes | Yes |
-| Create/edit resources | Yes | Yes | No |
-| Manage workspace members | Yes | No | No |
-| Invite users to workspace | Yes | No | No |
-
----
-
-## FAQ
-
-
-
- Yes. A user can be a member of multiple workspaces with different roles in each.
-
-
- Yes. A user can be a Workspace Admin in one workspace and a Workspace Viewer in another.
-
-
- You still have full Workspace Admin access. Org Admins and Owners automatically get admin access to every workspace.
-
-
- Yes, but they can only grant access to workspaces they manage. They cannot grant access to other workspaces.
-
-
- No. Every organization must have at least one Owner. Transfer ownership to another user first.
-
-
- They lose access to all workspaces and all organization resources immediately. Their data (annotations, scores, etc.) is preserved.
-
-
diff --git a/src/pages/docs/roles-and-permissions/guides/manage-access.mdx b/src/pages/docs/roles-and-permissions/guides/manage-access.mdx
new file mode 100644
index 00000000..c62e3eac
--- /dev/null
+++ b/src/pages/docs/roles-and-permissions/guides/manage-access.mdx
@@ -0,0 +1,151 @@
+---
+title: "Manage access"
+description: "Set a team up from scratch, invite people, change what they reach, remove them cleanly, and share one thing outside the organization."
+---
+
+An organization arrives with one workspace and one person in it, and the shape you give it in the first hour is the shape it keeps, because a workspace cannot be deleted from the dashboard and a key cannot be moved between workspaces. Taking access away is the half that goes wrong, since removing somebody ends their sign-in and leaves every API key they created working. This guide covers both ends and everything between.
+
+## Before you start
+
+- You are an Owner or an Admin, the two roles that can create workspaces and open **Settings > Members**. A Workspace Admin manages their own workspace instead, from the switcher
+- You know which groups of people must not see each other's work, since that is the only question a workspace answers
+- You have the email address of everyone you are inviting, since an invite will not send without one
+
+## Decide how many workspaces you need
+
+One workspace is enough if everyone is allowed to see everything. Add a second when one group must not see another group's work, or when you want production and staging kept apart. [What is scoped where](/docs/roles-and-permissions#what-is-scoped-where) lists what moves with the boundary and what does not.
+
+Your organization already has **Default Workspace**. Nothing in the dashboard deletes a workspace, this one included, so use it for one of your teams, leave it empty, or ask the Future AGI team to remove it.
+
+There are two ways to add one, and both open the same dialog. Either open the **workspace switcher** at the top of the left sidebar, hover the workspace name and choose **Create Workspace**, or go to **Settings > Workspaces** and click **Create New Workspace**. Name it and click **Create workspace**. You become its admin, and reusing a name gives you **Workspace with this name already exists**.
+
+
+The switcher does more than switch. It creates workspaces, moves you between workspaces and organizations, opens Settings, and is where a Workspace Admin invites people. You will be back in it throughout this guide.
+
+
+## Pick a role for each person
+
+Everyone gets two roles. The organization role decides who they can manage and whether they reach organization settings and billing; the workspace role decides what they can do with the work.
+
+| What they need to do | Organization role | Workspace role |
+|---|---|---|
+| Set the organization up | Owner | Every workspace, automatically |
+| Share the account, the people and the billing with you | Admin | Every workspace, automatically |
+| Run one workspace and manage the people in it | Member | Workspace Admin |
+| Build and edit inside one workspace | Viewer | Workspace Member |
+| Read one workspace without changing it | Viewer | Workspace Viewer |
+
+
+**Owners and Admins reach every workspace, automatically and permanently.** You cannot make someone an Admin and keep one workspace out of their reach. If a boundary matters, make them a Member or Viewer and add them only to the workspaces they should see.
+
+
+To give someone control of one workspace and nothing else, make them an organization **Member** and a **Workspace Admin** there. They can then invite into it and manage its members, without reaching billing, organization settings, or anyone else's workspace.
+
+
+**Why the Workspace Members above are organization Viewers, not Members.** A team lead can only manage people whose organization role is lower than their own. If the people they lead are also organization Members, the lead's row menu is disabled with *You cannot manage a user at or above your own level.*
+
+Organization Viewer takes almost nothing away here. The **Workspace Member** role still creates, edits and shares everything in that workspace, and still opens the workspace's own Integrations and AI Providers tabs. What it drops is the organization-level **AI Providers** page in Settings.
+
+
+## Invite people
+
+There are two ways in, and which one you get depends on your role.
+
+**From the Members page.** Go to **Settings > Members** and click **Invite User**. This is the Owner and Admin path, and the only one that carries an Organization Role field.
+
+**From the workspace switcher.** Choose **Invite members**. This is the Workspace Admin path, and it appears only while they are standing in a workspace they administer. The workspaces picker then offers every workspace they belong to, so someone who administers one and is a plain member of another can still invite into both.
+
+Enter the addresses in **Emails**, comma separated, then pick the **Organization Role**, the **Workspace Role**, and the **Workspaces** it applies to. One invite carries one of each and every address on it gets all three, so send one invite per group rather than one for the whole team. Granting Admin or Owner removes both workspace fields and replaces them with *Owner and Admin roles have automatic access to all workspaces.*
+
+
+
+*Granting Admin or Owner removes the workspace fields, because those roles reach every workspace already*
+
+The new row shows as **Pending** until the person accepts, or **Active** immediately if the address already has a Future AGI account. A Pending row carries exactly two actions, **Resend the invite** and **Cancel invite**.
+
+An invite is valid for 7 days, after which it shows as Expired. The link inside the email expires sooner than the invite itself, so resend rather than waiting if the link stops working. Resending issues a fresh link and restarts the window.
+
+
+A Workspace Admin's invite has no Organization Role field, so they cannot set anyone's organization role and only an Owner or Admin can change it afterwards. If your team leads onboard their own people, check **Settings > Members** afterwards and set the organization role yourself.
+
+
+## Hand out the API keys
+
+Your SDK and your traces authenticate with a platform API key.
+
+
+**Switch into the right workspace first.** A key belongs to whichever workspace you have open when you create it, and it cannot be moved afterwards. Make the key for `research` while you are inside `research`.
+
+
+Open **Build > Keys** in the left sidebar and click **Add API Key**. Only Owners, Admins and Workspace Admins can open that page, so decide who issues keys before you start. [API Keys](/docs/admin-settings/api-keys) walks the dialog, the copy step and rotation.
+
+## Change someone's access
+
+**Settings > Members** lists everyone with their name, organization role, workspaces, email, status and start date, and filters for status and role. Each row carries **Edit user info** and **Remove from organization**.
+
+
+
+*Every person carries one organization role and the workspaces they belong to*
+
+You can change or remove anyone whose organization role is lower than yours, and an Owner can also change another Owner. Where you cannot, the row's menu is disabled and says why: *You can't edit your own role*, or *You cannot manage a user at or above your own level.*
+
+**Edit user info** holds an Organization Role and a Workspace Role. Setting someone to Member or Viewer adds a required **Workspaces** field, because *Members and Viewers need explicit workspace access.* Any workspace you leave unselected is removed from them in the same step, so read that field before you save it.
+
+- Promoting someone to Admin or Owner makes them a Workspace Admin in every workspace at once
+- Demoting an Admin to Member or Viewer asks you to pick the workspaces they keep
+- The last remaining Owner can neither be demoted nor removed. Promote a second Owner first
+
+## Remove someone
+
+Removing someone from the organization asks you to confirm, then ends their sign-in and marks them Deactivated. Removing them from a single workspace leaves their organization membership intact. A few things are blocked outright: you cannot remove yourself, anyone from their last workspace, an Owner or Admin from a workspace, or the last remaining Owner.
+
+Removal does not delete anything a person produced. Annotations, scores and other output stay in place.
+
+Reactivating is not something the dashboard offers. A removed person is marked Deactivated and no control anywhere brings them back, so contact the Future AGI team if somebody has to be restored.
+
+
+**A platform API key belongs to the organization, not to the person who created it.** Removing someone does not disable any key they made, and anything still using that key keeps working.
+
+Go through **Build > Keys** in **every workspace they belonged to**, because that page only ever shows the keys of the workspace you have open. Check the **Created By** column and disable theirs. Deleting needs an Owner, so if you are an Admin, disable it now and hand the deletion to an Owner.
+
+
+Two more things survive a removal. Any share link they created still works, and a dataset link cannot be withdrawn from the dashboard at all. And there is no activity log anywhere in the product, so a record of what they changed has to come from Future AGI rather than from a screen.
+
+## Require two-factor authentication
+
+Owners and Admins reach [**Settings > Org Settings**](/docs/admin-settings/organization-settings), which holds the organization name and the security policy. Under **Organization Security** there is one toggle, **Require 2FA for all members**, and turning it on makes every member of the organization set up two-factor authentication. You have to enable it on your own account first, and the page links straight to Profile Settings so you can.
+
+## Share outside your organization
+
+A share link grants access to a single resource without granting a role, which makes it the fastest way to show a customer or an auditor one thing. It is also the one access path that ignores workspaces entirely. Anyone who can create or edit in a workspace can make one; for a Workspace Viewer the **Share** button is greyed out.
+
+**A dataset** shares its own address. The dialog gives you the link, a copy button, **Cancel** and **Done**, and says *Anyone with the link will be able to view the data.* There is no restricted option, no expiry and no revoke.
+
+**An Observe project** shares a separate `app.futureagi.com/shared/...` address, and its dialog reopens at any time with the current setting under **Who can access**. **Restricted** is the default and only the people you add can open it; **Anyone with the link** drops the sign-in entirely. A restricted share also takes email addresses directly, and those people sign in without joining your organization.
+
+
+**A dataset link cannot be taken back from the dashboard.** Contact the Future AGI team if one has to be withdrawn, and send one only where public access to that data is acceptable.
+
+An Observe project can be set back to **Restricted**, which is the only control the dashboard gives you over a link already sent. Nothing anywhere issues a fresh URL or sets an expiry.
+
+
+## Check it worked
+
+Three read-only checks close the setup out.
+
+- **Settings > Members** lists everyone with their role, their workspaces, and Active or Pending
+- **Settings > Workspaces** lists every workspace with its admins
+- Ask one teammate to sign in. They should see their own workspaces in the switcher and nothing else
+
+The setup is done when every person is on the Members page with the role you intended, and a Member or Viewer signing in sees only the workspaces you put them in.
+
+## Dive deeper
+
+
+
+ Every action against every role, and what to check when someone cannot see something
+
+
+ Create, disable and rotate the keys the SDK uses
+
+
diff --git a/src/pages/docs/roles-and-permissions/index.mdx b/src/pages/docs/roles-and-permissions/index.mdx
new file mode 100644
index 00000000..539f0311
--- /dev/null
+++ b/src/pages/docs/roles-and-permissions/index.mdx
@@ -0,0 +1,168 @@
+---
+title: "Roles & Permissions Overview"
+description: "Two levels of access, the roles that live on each, and where the boundary between two teams actually sits"
+---
+
+Access on Future AGI is decided in two places, not one. Where the plan and the people live is one boundary; where the work lives is another. Almost every access problem is the same shape: the right role, held at the wrong level.
+
+## What is access control on Future AGI?
+
+Every account has an **organization**, and inside it one or more **workspaces**. You hold a role in each:
+
+- Your **organization role** is one of Owner, Admin, Member or Viewer. It decides who you can manage, and whether you reach organization settings and billing
+- Your **workspace role** is one of Workspace Admin, Workspace Member or Workspace Viewer. It decides what you can do with the work inside that workspace
+
+
+
+The organization is the billing boundary. The workspace is the data boundary. Every organization is created with one workspace, called **Default Workspace**, and workspace names are unique inside an organization.
+
+## Organization roles
+
+Everyone holds one of four. They rank in this order, Owner highest and Viewer lowest, and the ordering decides who can invite and manage whom. These are the descriptions the product itself shows you.
+
+
+
+ Full control. Can manage billing, members, and transfer ownership
+
+
+ Full control on manage settings, members, and permissions
+
+
+ Collaborate within the space, accessing tools and tasks shared with them
+
+
+ Read-only access to shared resources
+
+
+
+An organization keeps at least one Owner at all times, so ownership moves by promoting a second Owner and then demoting the first. An Admin reaches billing and the plan on the same terms as an Owner, but cannot change an Owner or another Admin.
+
+
+Owners and Admins are **Workspace Admins** in every workspace, automatically. They need no workspace membership of their own, promoting someone grants that access everywhere at once, and demoting them asks you to pick the workspaces they keep.
+
+
+## Workspace roles
+
+A Member or Viewer sees nothing in a workspace until they are added to it. Their role in that workspace is one of three.
+
+| Role | View | Create and edit | Manage workspace members |
+|---|---|---|---|
+| Workspace Admin | Yes | Yes | Yes, for people whose organization role is lower |
+| Workspace Member | Yes | Yes | No |
+| Workspace Viewer | Yes | No | No |
+
+The last column carries a second condition. A Workspace Admin manages the members of their workspace, and the organization role still applies on top, so they can change or remove only the people whose organization role is lower than their own.
+
+Every Member and Viewer needs at least one workspace, and the invite form will not send without one. Someone with no workspace sees an empty product on sign-in.
+
+## When both roles apply
+
+Inside a workspace, the workspace role is the one that applies, in both directions. An organization Viewer added as Workspace Member can create, edit and share there. An organization Member added as Workspace Viewer cannot: Add Dataset, Add Row, Add Column, Run Prompt, Evaluate, Share and Create prompt are all greyed out for them.
+
+One person can hold a different role in each workspace, and the difference is visible on the same screen. A dataset gives you Add Row, Add Column, Run Prompt, Evaluate and Share where you are a Workspace Member, and greys all of those out where you are a Workspace Viewer.
+
+A Workspace Admin cannot open organization settings or create a workspace. Both need an organization Admin or Owner. The role does give **Invite members** in the workspace switcher, the Members tab inside that workspace's own settings, and the **Build > Keys** page.
+
+ ORG["Their organization role"]
+ ORG --> RANK["Who they can manage, and billing and organization settings"]
+ ORG -->|"Owner or Admin"| ALL["Workspace Admin in every workspace"]
+ ORG -->|"Member or Viewer"| ADDED["Added to this workspace?"]
+ ADDED -->|"no"| NONE["No access, workspace not listed"]
+ ADDED -->|"yes"| WS["Their workspace role decides"]
+ ALL --> WORK["What they can do with the work"]
+ WS --> WORK
+ WORK --> QUEUE["Inside a queue, the queue role applies instead"]`} />
+
+## What is scoped where
+
+This boundary decides what a teammate in another workspace can see.
+
+
+
+ Datasets, traces, prompts, evaluations and annotation queues, plus knowledge bases, custom models, playground graphs, optimization runs and that workspace's own connections
+
+
+ Members, roles and invites, the plan and everything on the bill, resource and rate limits, gateway keys and gateway request logs, and the organization Settings pages
+
+
+
+Integrations and AI Providers appear on both sides because there are two of each: an organization Settings page, and a tab inside every workspace. Reaching one does not give you the other.
+
+Future AGI's built-in evaluations are available in every workspace of every organization. An evaluation template you build yourself belongs to the workspace you built it in, so rebuild it where it is needed, or keep shared evaluations in a workspace everyone belongs to.
+
+## What the boundary does not cover
+
+Separating teams into workspaces separates their work. Four things stay shared across the whole organization.
+
+| Not separated | What that means |
+|---|---|
+| The gateway | Every role opens every page under **Gateway**, and the request logs are stamped with the organization rather than a workspace |
+| Where a key can send | A key always writes to its own organization, whichever one you have open in the dashboard |
+| What a key can be aimed at | Traces are fixed to the key's workspace, but other SDK and API calls can name any workspace you have access to in the same organization |
+| Usage and billing | One plan, one balance, one invoice. **Usage Summary** is open to every role and breaks consumption down by workspace |
+
+Three consequences follow:
+
+- Anyone who can sign in sees every team's gateway traffic, so keep a team's traffic off the gateway if it has to stay private
+- Every role can see what every team is using on **Usage Summary**
+- A key is scoped by who holds it, not by where it was made
+
+
+**Gateway** is in the sidebar for everyone, including a Viewer, and every page under it opens: Providers, API Keys, Guardrails, Fallbacks, the request logs, budgets and webhooks. Treat gateway configuration as visible to your whole organization.
+
+Only reading is open to everyone. Writing is still checked, just later than elsewhere. The gateway leaves its create buttons live instead of greying them out, then refuses on submit with **Write access denied to this workspace**.
+
+
+## Where a key lands
+
+A [platform API key](/docs/admin-settings/api-keys) belongs to one organization for good, and inside it to the workspace you had open when you created it. Nothing in the **Add API Key** dialog says so and there is no field to change it, so switch into the workspace before you create the key.
+
+Traces always land in the workspace the key was created in, and a workspace header on a trace export is ignored. The one exception is the starter `system_org_key`, which was never created in a workspace and lands in the organization's default one. Other SDK and API calls can name a different workspace on the request, and they resolve in this order:
+
+1. An `X-Workspace-Id` header or a `workspace_id` query parameter takes precedence, provided that workspace is in the same organization and you have access to it
+2. Otherwise the workspace the key was created in
+3. Otherwise the workspace you last used, then the first workspace you belong to, and if you belong to none, the organization's default workspace
+
+
+Data in the wrong place is almost always the key. Make one key per workspace, name it after the workspace, and create each one while you are inside it.
+
+
+## One person, many organizations
+
+One person can belong to several organizations, with a different role in each. Organizations share nothing: separate workspaces, separate members, separate plan, separate billing, separate keys. Two teams that need separate gateway logs or separate invoices need separate organizations, because neither splits by workspace.
+
+Move between them from the switcher at the top of the sidebar. Future AGI remembers where you were, so the organization and workspace you last used are where you land next time, on any device.
+
+## Annotation queue roles
+
+[Annotation queues](/docs/annotations/concepts/queues-and-items) carry one more set of roles, granted per person per queue. They control what someone can do to the items in a queue, not who can see it: anyone with access to the workspace can browse it.
+
+| Queue role | What it covers |
+|---|---|
+| Annotator | Annotates the items assigned to them |
+| Reviewer | Reviews other people's annotations and sends work back for rework |
+| Manager | Manages the queue itself, its settings and its people |
+
+Each person gets three independent checkboxes, one per role, so they combine freely, and whoever creates the queue is added with all three ticked. Inside a queue the queue role applies instead of the workspace role, so an Annotator can annotate there even if they cannot create or edit anything else in the workspace.
+
+Two settings on the queue change how the work is handed out. **Auto-assign items to all annotators** gives every annotator every item, and **Submissions per item** sets how many annotators must label each one, at most the number you have added.
+
+## Why it matters
+
+The combination people get wrong is a team lead who cannot manage their own team. Making the lead an organization Member and a Workspace Admin looks right, and it fails the moment the people they lead are also organization Members, because a Workspace Admin can only change or remove people whose organization role is lower than their own. Put the people they lead in as organization Viewers and the same setup works.
+
+The other one is an isolation promise. The workspace does its job completely for datasets, traces, prompts and evaluations, and it does not contain a credential, a gateway log or a bill. Read the four rows above before you tell a customer two teams are separated.
+
+## Start here
+
+
+
+ Set the team up, invite people, change what they reach, and share outside the organization
+
+
+ Every action against every role, plus what to check when someone cannot see something
+
+
diff --git a/src/pages/docs/roles-and-permissions/reference/permissions.mdx b/src/pages/docs/roles-and-permissions/reference/permissions.mdx
new file mode 100644
index 00000000..5c42a626
--- /dev/null
+++ b/src/pages/docs/roles-and-permissions/reference/permissions.mdx
@@ -0,0 +1,183 @@
+---
+title: "Permission reference"
+description: "Every action against every role, what each role sees in Settings, and what to check when someone cannot see something"
+---
+
+## By organization role
+
+| Action | Owner | Admin | Member | Viewer |
+|---|---|---|---|---|
+| See the workspaces they belong to | Yes | Yes | Yes | Yes |
+| Reach every workspace automatically | Yes | Yes | No | No |
+| Create a workspace | Yes | Yes | No | No |
+| Invite and manage members | Yes | Yes | No | No |
+| Manage Owners and other Admins | Yes | No | No | No |
+| Open organization settings | Yes | Yes | No | No |
+| Open billing and pricing | Yes | Yes | No | No |
+| Open AI Providers in Settings | Yes | Yes | Yes | No |
+| Open the Keys page | Yes | Yes | No | No |
+| Open Usage Summary | Yes | Yes | Yes | Yes |
+| Reach the gateway | Yes | Yes | Yes | Yes |
+
+What a Member or Viewer can do inside a workspace comes from their workspace role, below. A Member or Viewer who is a Workspace Admin somewhere can also invite into that workspace and open the Keys page.
+
+## By workspace role
+
+| Workspace action | Workspace Admin | Workspace Member | Workspace Viewer |
+|---|---|---|---|
+| View the work in the workspace | Yes | Yes | Yes |
+| Create and edit | Yes | Yes | No |
+| Create a share link | Yes | Yes | No |
+| Create anything in the gateway | Yes | Yes | No |
+| Manage workspace members | Yes, for people whose organization role is lower | No | No |
+| Invite into that workspace | Yes | No | No |
+| Open that workspace's Integrations and AI Providers | Yes | Yes | No |
+| Open that workspace's Members tab | Yes | No | No |
+| Open the Keys page | Yes | No | No |
+
+
+Managing workspace members still follows the organization role. A Workspace Admin whose organization role is Member can change or remove the people in their workspace whose organization role is Viewer, and the rest of the rows are disabled. The two actions on a row are **Edit user info** and **Remove from workspace**.
+
+
+## Settings pages by role
+
+Open Settings from the workspace switcher at the top of the sidebar. It is a grouped tree, and this list follows your **organization** role only, so it is the same in every workspace you switch to.
+
+| Settings page | Owner | Admin | Member | Viewer |
+|---|---|---|---|---|
+| Profile | Yes | Yes | Yes | Yes |
+| Usage Summary | Yes | Yes | Yes | Yes |
+| AI Providers | Yes | Yes | Yes | No |
+| Members | Yes | Yes | No | No |
+| Integrations | Yes | Yes | No | No |
+| Falcon AI Connectors | Yes | Yes | No | No |
+| Plans & Pricing | Yes | Yes | No | No |
+| Billing | Yes | Yes | No | No |
+| MCP Server | Yes | Yes | No | No |
+| Org Settings | Yes | Yes | No | No |
+| Workspaces | Yes | Yes | No | No |
+
+Below those sits **Your Workspaces**, which lists every workspace you belong to and opens that workspace's own settings. Owners and Admins see every workspace in the organization there.
+
+
+**Integrations** and **AI Providers** each name two different screens. The ones above are organization settings. Each workspace also has its own Integrations and AI Providers tabs, holding that workspace's own connections. Reaching one does not give you the other.
+
+
+## Workspace settings tabs by role
+
+| Your workspace role | Tabs you get |
+|---|---|
+| Workspace Admin | General, Members, Integrations, AI Providers |
+| Workspace Member | General, Integrations, AI Providers |
+| Workspace Viewer | General, and it has no Save button |
+
+**General** holds the workspace name and a **Save Changes** button, so a workspace can be renamed at any time even though it cannot be deleted.
+
+## Billing pages by role
+
+[Billing](/docs/billing) is handled at the organization. There is one plan, one balance and one set of limits, and every workspace draws on them, so adding a member or a workspace does not change the plan.
+
+**Plans & Pricing** and **Billing** are open to Owners and Admins, both with the same controls: the plan, the invoices, **Add Budget** and **Add Card**. **Usage Summary** is open to every role and breaks consumption down by workspace. All three are Future AGI Cloud only, and self-hosted deployments get a **License** page instead.
+
+## Who can grant what
+
+| Who is inviting | What they can grant | Which workspaces |
+|---|---|---|
+| Owner | Any organization role, up to Owner | Any |
+| Admin | Admin, Member, or Viewer. Owner is not offered | Any |
+| Workspace Admin | A workspace role only | Any workspace they belong to, but only from one they administer |
+
+You can grant your own role or anything below it, never above. An Admin cannot create an Owner: the Organization Role list simply does not contain it.
+
+## Key actions
+
+**Build > Keys** carries three actions.
+
+| Action | What it does | Who |
+|---|---|---|
+| Add API Key | Creates a key bound to the workspace you have open | Owner, Admin, Workspace Admin |
+| Disable Key | Turns off the key and its secret together. The row gains a **Disabled** badge and the menu changes to **Re-enable key** | Owner, Admin, Workspace Admin |
+| Delete Key | Removes the key and its secret permanently, and cannot be undone | Owner only |
+
+
+**Delete Key** is offered to everyone who can open the page, but only an Owner's goes through. [API Keys](/docs/admin-settings/api-keys#managing-keys) covers what everyone else gets instead.
+
+
+## When someone cannot see something
+
+Somebody cannot see something, and it is nearly always one of three things: they were never added to the workspace, their workspace role is read-only, or the page they want is not in their role's navigation.
+
+| What they say | What to check |
+|---|---|
+| "I cannot see the workspace at all" | They were never added to it. Add them from **Settings > Members** |
+| "I can see it but I cannot create anything" | They are a Workspace Viewer there. Change their workspace role |
+| "I cannot see your dataset or your evaluation" | Those live in the workspace they were made in. Add the person to that workspace |
+| "That Settings page is missing for me" | The page is not in their role's navigation, and typing the address does not get them in |
+| "I clicked it and nothing happened" | Usually a permission rather than a fault. Compare their role against the grids above |
+
+
+Go by your navigation. If a Settings page is not listed there, your role cannot reach it, and the address does not say so. Depending on the page you get a 404, a silent return to Datasets, or the page itself with buttons that do nothing. None of those mean the feature is missing.
+
+
+The gateway is the one place that breaks this pattern. Its buttons stay live for everyone and refuse on submit with **Write access denied to this workspace**, so somebody who cannot create in a workspace finds out one click later there than anywhere else.
+
+## What the dashboard cannot do
+
+| What you need | Why the dashboard cannot do it |
+|---|---|
+| A workspace deleted | There is no delete action anywhere in the dashboard |
+| A dataset share link withdrawn | Its dialog has no revoke, no expiry and no regenerate. An Observe project can at least be set back to Restricted |
+| Someone you removed brought back | Removal marks them Deactivated and the dashboard offers no way to undo it |
+
+Ask the Future AGI team through [support](https://futureagi.com/contact-us) for all three.
+
+A fourth needs settling before you promise anything to a compliance reviewer. The dashboard has no activity or audit log, so you cannot pull a record of who changed whose role. Ask Future AGI whether one exists behind the product before you commit to producing it.
+
+
+**What these pages cover.** They answer who can reach what in the dashboard, and what happens when they try. They do not cover how long a sign-in or token stays valid, what happens to data after an account closes, or what is retained where.
+
+
+## Common questions
+
+**Can the same person be in more than one organization?**
+
+Yes, with a different role in each. The organizations share nothing, and you move between them from the switcher at the top of the sidebar.
+
+**I have an organization role and a workspace role. Which one applies?**
+
+Owners and Admins are Workspace Admins everywhere. For everyone else the workspace role decides, in both directions.
+
+**I demoted an Admin to Member. Do they still see every workspace?**
+
+Only the ones you selected during the demotion. Setting someone to Member or Viewer adds a required Workspaces field, and access to every unselected workspace is removed in the same step.
+
+**Can a Workspace Admin invite an Admin?**
+
+No. Their invite carries no Organization Role field, so they grant a workspace role only.
+
+**My SDK data is going to the wrong place. What should I check?**
+
+It is the key. A key belongs to one organization for good, so the wrong organization means you need a key made in the other one. The wrong workspace means traces are landing where the key was created and cannot be redirected, so make a new key inside the workspace you want. If you never made the key yourself, check whether you are using the starter `system_org_key`, which lands in the organization's default workspace.
+
+**Can I give one team its own gateway logs, or its own bill?**
+
+Not inside one organization. Gateway keys, gateway request logs, the plan and the invoice all belong to the organization. Separate logs or separate bills mean separate organizations.
+
+**What happens to someone's work after they are removed?**
+
+It is preserved, and their sign-in stops immediately. Their API keys are the exception and keep working, because a key belongs to the organization rather than the person.
+
+**Do you support SSO?**
+
+Yes. SAML, along with Google and GitHub sign in, and passkeys. Talk to the Future AGI team before setting SAML up. Once it is configured, password resets are turned off and new sign ups have to come through SAML, though existing password and social logins keep working.
+
+## Keep exploring
+
+
+
+ The two levels, the roles on each, and where the boundary sits
+
+
+ Put a role change or a removal into effect
+
+
+
+*Granting Admin or Owner removes the workspace fields, because those roles reach every workspace already*
+
+The new row shows as **Pending** until the person accepts, or **Active** immediately if the address already has a Future AGI account. A Pending row carries exactly two actions, **Resend the invite** and **Cancel invite**.
+
+An invite is valid for 7 days, after which it shows as Expired. The link inside the email expires sooner than the invite itself, so resend rather than waiting if the link stops working. Resending issues a fresh link and restarts the window.
+
+
+
+*Every person carries one organization role and the workspaces they belong to*
+
+You can change or remove anyone whose organization role is lower than yours, and an Owner can also change another Owner. Where you cannot, the row's menu is disabled and says why: *You can't edit your own role*, or *You cannot manage a user at or above your own level.*
+
+**Edit user info** holds an Organization Role and a Workspace Role. Setting someone to Member or Viewer adds a required **Workspaces** field, because *Members and Viewers need explicit workspace access.* Any workspace you leave unselected is removed from them in the same step, so read that field before you save it.
+
+- Promoting someone to Admin or Owner makes them a Workspace Admin in every workspace at once
+- Demoting an Admin to Member or Viewer asks you to pick the workspaces they keep
+- The last remaining Owner can neither be demoted nor removed. Promote a second Owner first
+
+## Remove someone
+
+Removing someone from the organization asks you to confirm, then ends their sign-in and marks them Deactivated. Removing them from a single workspace leaves their organization membership intact. A few things are blocked outright: you cannot remove yourself, anyone from their last workspace, an Owner or Admin from a workspace, or the last remaining Owner.
+
+Removal does not delete anything a person produced. Annotations, scores and other output stay in place.
+
+Reactivating is not something the dashboard offers. A removed person is marked Deactivated and no control anywhere brings them back, so contact the Future AGI team if somebody has to be restored.
+
+
+
+The organization is the billing boundary. The workspace is the data boundary. Every organization is created with one workspace, called **Default Workspace**, and workspace names are unique inside an organization.
+
+## Organization roles
+
+Everyone holds one of four. They rank in this order, Owner highest and Viewer lowest, and the ordering decides who can invite and manage whom. These are the descriptions the product itself shows you.
+
+