From 8ee00caa129f9d7e7c02edbcaf11a962ff1f6734 Mon Sep 17 00:00:00 2001
From: Khaleel Al-Adhami <khaleel.aladhami@gmail.com>
Date: Mon, 20 Jul 2026 12:31:48 -0700
Subject: [PATCH 1/2] docs: add Organizations & Permissions section under AI
 builder

Add docs/ai_builder/organization/ covering organizations end to end: overview, members & seats, roles & permissions, managing project access, custom roles, verified domains, SSO, deployment approvals, audit logs, moving projects & apps, and bring-your-own-cloud. Wire the section into the AI builder docs sidebar and cross-link from hosting/adding-members and hosting/billing.
---
 docs/ai_builder/organization/audit_logs.md    |  55 +++++++++
 .../organization/cloud_providers.md           |  84 +++++++++++++
 docs/ai_builder/organization/custom_roles.md  |  98 +++++++++++++++
 .../organization/deployment_approvals.md      |  57 +++++++++
 docs/ai_builder/organization/domains.md       |  79 ++++++++++++
 docs/ai_builder/organization/members.md       |  89 ++++++++++++++
 .../organization/moving_projects_and_apps.md  |  67 ++++++++++
 docs/ai_builder/organization/overview.md      | 115 ++++++++++++++++++
 .../ai_builder/organization/project_access.md |  75 ++++++++++++
 .../organization/roles_and_permissions.md     | 111 +++++++++++++++++
 docs/ai_builder/organization/sso.md           |  54 ++++++++
 .../docpage/sidebar/sidebar_items/ai.py       |  16 +++
 .../docpage/sidebar/sidebar_items/item.py     |   1 +
 docs/hosting/adding-members.md                |   5 +
 docs/hosting/billing.md                       |   5 +
 15 files changed, 911 insertions(+)
 create mode 100644 docs/ai_builder/organization/audit_logs.md
 create mode 100644 docs/ai_builder/organization/cloud_providers.md
 create mode 100644 docs/ai_builder/organization/custom_roles.md
 create mode 100644 docs/ai_builder/organization/deployment_approvals.md
 create mode 100644 docs/ai_builder/organization/domains.md
 create mode 100644 docs/ai_builder/organization/members.md
 create mode 100644 docs/ai_builder/organization/moving_projects_and_apps.md
 create mode 100644 docs/ai_builder/organization/overview.md
 create mode 100644 docs/ai_builder/organization/project_access.md
 create mode 100644 docs/ai_builder/organization/roles_and_permissions.md
 create mode 100644 docs/ai_builder/organization/sso.md

diff --git a/docs/ai_builder/organization/audit_logs.md b/docs/ai_builder/organization/audit_logs.md
new file mode 100644
index 00000000000..22b9c836ea9
--- /dev/null
+++ b/docs/ai_builder/organization/audit_logs.md
@@ -0,0 +1,55 @@
+---
+tags: Organization
+description: Review a record of who did what in your Reflex organization and projects, with search, filtering, and CSV export.
+---
+
+# Audit Logs
+
+```python exec
+import reflex as rx
+```
+
+An **audit log** records the important actions taken in your organization: who did what, and when. It answers questions like *who removed this member?* or *when was this domain verified?* for security reviews, compliance, or day-to-day troubleshooting.
+
+Reflex keeps audit logs at two levels: one for the **organization** and one for each **project**.
+
+## The organization audit log
+
+Open your organization's **Settings → Audit log** to see organization-wide activity, such as member and role changes, domain and single sign-on changes, and other administrative actions.
+
+Each entry shows:
+
+- **Time**: when the action happened.
+- **Event**: what happened, with a short summary.
+- **Actor**: who did it.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/audit-logs/org_audit_log.webp",
+    alt="The organization audit log table showing Time, Event, and Actor columns with a search box and event filter",
+    class_name="rounded-md h-auto",
+)
+```
+
+```md alert info
+# Who can view the audit log
+The organization audit log is available to organization **admins** and **managers**. Members don't have access.
+```
+
+### Finding an entry
+
+The audit log supports:
+
+- **Search** across events, actors, and details.
+- **Filter** by event type.
+- **Export to CSV** for reporting or to share with your security team.
+- **Refresh** for the latest activity.
+
+## Project audit logs
+
+Each project has its own audit log, under the project's **Settings → Audit log**, covering activity within that project. Viewing it requires the **View audit log** permission, which comes with the project **Admin** role and can be added to a [custom role](/docs/ai/organization/custom-roles/).
+
+## Related
+
+- [Roles & permissions](/docs/ai/organization/roles-and-permissions/) — who can see each audit log.
+- [Deployment approvals](/docs/ai/organization/deployment-approvals/) — a checkpoint before deployments run.
diff --git a/docs/ai_builder/organization/cloud_providers.md b/docs/ai_builder/organization/cloud_providers.md
new file mode 100644
index 00000000000..8028f5c7ab8
--- /dev/null
+++ b/docs/ai_builder/organization/cloud_providers.md
@@ -0,0 +1,84 @@
+---
+tags: Organization
+description: Connect your own cloud provider account to a Reflex organization so its apps deploy to infrastructure you control.
+---
+
+# Bring Your Own Cloud
+
+```python exec
+import reflex as rx
+```
+
+By default, apps run on Reflex's infrastructure. On the **Enterprise** plan, you can connect your organization's own cloud account instead, so apps run on infrastructure you control and are billed directly by your provider. This is often required by security, procurement, or data-residency policies.
+
+You connect a cloud account once, at the organization level, under **Settings → Cloud providers**. The whole organization can then deploy to it.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/cloud-providers/providers_overview.webp",
+    alt="The Cloud providers tab showing Google Cloud connected, with AWS and Azure greyed out and unavailable",
+    class_name="rounded-md h-auto",
+)
+```
+
+```md alert info
+# Who can connect a cloud provider
+Only organization admins can connect, view, or remove cloud provider accounts. Connecting is an Enterprise feature; [contact sales](https://reflex.dev/pricing/) to enable it.
+```
+
+## Supported providers
+
+**Google Cloud** is available now. **AWS** and **Azure** aren't available yet.
+
+## Connecting Google Cloud
+
+Connecting Google Cloud takes two steps:
+
+1. **Run the setup.** Reflex provides a script that prepares your Google Cloud project and creates the credentials it needs. Select **Copy agent setup** to copy a prompt you can hand to an AI coding agent to run the steps for you.
+2. **Enter the details.** Select **Connect GCP** and paste the values the setup produced:
+   - the **service account key** (the contents of the key file),
+   - the **project number**,
+   - the **Cloud Run region** where apps should run, and
+   - optionally, an **Artifact Registry repository** name.
+
+Reflex validates the details and marks the provider connected.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/cloud-providers/connect_gcp.webp",
+    alt="The Connect your GCP account dialog with fields for the service account key, project number, and region",
+    class_name="rounded-md h-auto",
+)
+```
+
+```md alert info
+# Your credentials are kept safe
+The service account key is stored encrypted and used only to deploy and manage your organization's apps.
+```
+
+Once connected, the tab shows the account's status, project, region, and repository.
+
+## Removing a connection
+
+To disconnect, open the connected provider and select **Remove connection**. Two effects:
+
+- New deployments to that cloud fail until an admin reconnects an account.
+- Apps already running there keep running, but Reflex can't manage them.
+
+## Deploying to your own cloud
+
+Connecting an account here lets your organization's apps target your cloud. You can also deploy to your own cloud from the command line. For the full workflow and provider details, see:
+
+- [Bring Your Own Cloud](/docs/hosting/bring-your-own-cloud/) — deploying to AWS, GCP, or Azure from the command line.
+- [Deploy to GCP Cloud Run](/docs/hosting/deploy-to-gcp/) — a detailed Google Cloud walkthrough.
+
+## Workload isolation and namespaces
+
+Each organization's apps run in their own isolated space on the underlying infrastructure, separate from other organizations. With bring-your-own-cloud, that isolation is inside your account.
+
+This separation is called a *namespace*. Reflex sets it up and manages it; you don't configure it yourself. Enterprise customers with specific isolation requirements can discuss custom arrangements with the Reflex team.
+
+## Related
+
+- [Bring Your Own Cloud (CLI)](/docs/hosting/bring-your-own-cloud/) — deploy from the command line.
+- [Roles & permissions](/docs/ai/organization/roles-and-permissions/) — who can manage organization settings.
diff --git a/docs/ai_builder/organization/custom_roles.md b/docs/ai_builder/organization/custom_roles.md
new file mode 100644
index 00000000000..cdbcddb576a
--- /dev/null
+++ b/docs/ai_builder/organization/custom_roles.md
@@ -0,0 +1,98 @@
+---
+tags: Organization
+description: Create custom project roles in Reflex, built on a base access level with the specific permissions your team needs.
+---
+
+# Custom Roles
+
+```python exec
+import reflex as rx
+```
+
+The built-in project roles (Viewer, Editor, and Admin) cover most cases, but sometimes you need something in between: a contractor who can build and deploy apps but nothing else, or a reviewer who can approve deployments without editing. A **custom role** defines that combination.
+
+Custom roles are created per project, under **Settings → Roles**, by anyone with the project **Admin** role.
+
+```md alert info
+# Custom roles are for teams
+Custom roles matter once you have teammates on a project. Inviting teammates is an Enterprise feature; see [Managing project access](/docs/ai/organization/project-access/).
+```
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/custom-roles/roles_list.webp",
+    alt="The project Roles tab listing built-in roles and a custom role, with a New role button",
+    class_name="rounded-md h-auto",
+)
+```
+
+## How a custom role is built
+
+A custom role has two parts:
+
+1. **Base access level**: Viewer, Editor, or Admin. The role includes everything that level can do.
+2. **Additional permissions**: individual abilities you add on top of the base level.
+
+Pick the closest built-in level, then add the permissions you need.
+
+## Creating a role
+
+Select **New role** and fill in:
+
+- **Role name**: a label your team will recognize, such as *Support lead* or *Release manager*.
+- **Base access**: the starting level (Viewer, Editor, or Admin).
+- **Additional permissions**: the abilities to add on top.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/custom-roles/create_role_dialog.webp",
+    alt="The Create role dialog showing a name field, a base access dropdown, and grouped permission checkboxes",
+    class_name="rounded-md h-auto",
+)
+```
+
+Permissions that come with the base level are shown ticked and greyed out; they're part of the role and can't be removed. You choose everything else.
+
+### The permissions you can add
+
+| Group | Permission | What it allows |
+| --- | --- | --- |
+| **Project** | Create apps | Add new apps to the project |
+| | Create threads | Start new Build chats in the project |
+| | Rename project | Change the project's name |
+| | Delete project | Permanently delete the project |
+| **Secrets & integrations** | Manage integrations | Connect and configure integrations |
+| | View secret names | See which secrets exist (names only) |
+| | Reveal secret values | See the value of a secret |
+| | Edit secrets | Add, change, and remove secrets |
+| **Deployments** | Approve deployments | Approve or reject deployments that need sign-off |
+| **Activity** | View audit log | See the project's activity history |
+
+```md alert info
+# Some permissions come as a set
+Revealing or editing secret values requires seeing the secret names, so turning on **Reveal secret values** or **Edit secrets** also includes **View secret names**.
+```
+
+## Permissions you can't delegate
+
+Two abilities stay with the built-in **Admin** role and can't be added to a custom role:
+
+- **Managing members** (adding people and changing their roles)
+- **Managing roles** (creating and editing roles)
+
+Either one amounts to admin control. If someone needs it, give them the Admin role. Billing isn't part of project roles either; it comes from a person's [organization role](/docs/ai/organization/roles-and-permissions/).
+
+## Assigning a custom role
+
+A custom role appears in the role dropdown wherever you assign project roles: when [adding members](/docs/ai/organization/project-access/) and when changing an existing member's role. Each custom role shows its base level and how many permissions it adds.
+
+## Editing and deleting roles
+
+From the Roles tab, **edit** a custom role to rename it or change its permissions. Built-in roles can't be edited and carry a **Built-in** badge.
+
+To **delete** a custom role, first reassign any members using it to another role. Reflex won't delete a role while members are still assigned to it.
+
+## Related
+
+- [Managing project access](/docs/ai/organization/project-access/) — assign a role to members.
+- [Roles & permissions](/docs/ai/organization/roles-and-permissions/) — how the built-in roles are made up.
diff --git a/docs/ai_builder/organization/deployment_approvals.md b/docs/ai_builder/organization/deployment_approvals.md
new file mode 100644
index 00000000000..2bd1d759717
--- /dev/null
+++ b/docs/ai_builder/organization/deployment_approvals.md
@@ -0,0 +1,57 @@
+---
+tags: Organization
+description: Require deployments in a Reflex project to be approved before they go live, and manage the approval queue.
+---
+
+# Deployment Approvals
+
+```python exec
+import reflex as rx
+```
+
+You can require every deployment in a project to be **approved** before it runs. With approvals on, anyone can request a deployment, but it waits for sign-off from someone with permission. This gives the team a checkpoint before changes reach production.
+
+Deployment approvals are configured per project, under **Settings → Deploy approvals**.
+
+## Turning on approvals
+
+On the **Deploy approvals** tab, switch on **Require approval to deploy**. Deployments in the project are then held until approved.
+
+Only **project admins** can change this setting; others can see it but not change it.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/deployment-approvals/approval_policy.webp",
+    alt="The Deploy approvals tab with the Require approval to deploy toggle switched on",
+    class_name="rounded-md h-auto",
+)
+```
+
+## Who can approve
+
+Anyone with the **Approve deployments** permission can approve a deployment:
+
+- **Project admins**, who have it by default.
+- Anyone with a [custom role](/docs/ai/organization/custom-roles/) that grants **Approve deployments**.
+
+This separates who can request a deployment from who can approve one. For example, editors can deploy to staging while a release manager signs off on production.
+
+## The approval flow
+
+1. A team member starts a deployment as usual.
+2. With approvals on, the deployment is held instead of running.
+3. It appears under **Pending deployments** on the **Deploy approvals** tab, showing the app, who requested it, and where it would deploy (provider, region, and machine size).
+4. An approver selects **Approve** to run it, or **Reject** to stop it.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/deployment-approvals/pending_deployments.webp",
+    alt="A pending deployments list showing an app, the requester, deployment details, and Approve and Reject buttons",
+    class_name="rounded-md h-auto",
+)
+```
+
+## Related
+
+- [Custom roles](/docs/ai/organization/custom-roles/) — grant the Approve deployments permission.
+- [Audit logs](/docs/ai/organization/audit-logs/) — review approvals and other activity.
diff --git a/docs/ai_builder/organization/domains.md b/docs/ai_builder/organization/domains.md
new file mode 100644
index 00000000000..6a20dd34893
--- /dev/null
+++ b/docs/ai_builder/organization/domains.md
@@ -0,0 +1,79 @@
+---
+tags: Organization
+description: Verify a company email domain so teammates automatically join your Reflex organization.
+---
+
+# Verified Domains & Auto-Join
+
+```python exec
+import reflex as rx
+```
+
+Inviting people one at a time works for small teams. For a whole company, verify your email domain (such as `acme.com`) so anyone with a matching address joins the organization automatically, without an individual invitation.
+
+Verified domains are managed under **Settings → Domains** and are part of the **Enterprise** plan.
+
+## How it works
+
+1. Claim a domain your company owns.
+2. Prove ownership by adding a DNS record.
+3. Once verified, people with an email on that domain join automatically, including both new sign-ups and existing Reflex users.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/domains/domains_list.webp",
+    alt="The Domains tab showing a verified domain with an auto-join toggle and a pending domain awaiting verification",
+    class_name="rounded-md h-auto",
+)
+```
+
+## Claiming and verifying a domain
+
+Select **Add domain** and enter the domain to claim, such as `acme.com`. It appears with a **Pending** status and a set of DNS instructions.
+
+To verify ownership, add the **TXT record** shown (its Type, Name, and Value) with your DNS provider, where you manage your domain. Then return and select **Verify**.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/domains/dns_verification.webp",
+    alt="A pending domain card showing the TXT record type, name, and value to add, with a Verify button",
+    class_name="rounded-md h-auto",
+)
+```
+
+```md alert info
+# DNS changes take a little time
+After you add the record, it can take a few minutes to propagate. If verification fails at first, wait and try again.
+```
+
+Only one organization can verify a given domain.
+
+## Auto-join
+
+Once a domain is verified, **auto-join** is on by default:
+
+- **New people** who sign up with an email on the domain join the organization automatically.
+- **Existing Reflex users** with a matching email are added too.
+
+Turn auto-join **off** with the toggle to stop adding new people while keeping the domain verified. Use this to pause onboarding without removing the domain.
+
+### Syncing existing members
+
+If a domain shows **Sync incomplete**, some existing users on it haven't been added yet. Select **Sync members** to add them; it's safe to run at any time.
+
+### When you're out of seats
+
+If auto-join would add someone but the organization has no free [seats](/docs/ai/organization/members/), they go into the **Awaiting a seat** queue and hold no seat until an admin activates them. See [Members & seats](/docs/ai/organization/members/) to activate them.
+
+## Removing a domain
+
+Select the delete icon on a domain's card and confirm. New people on that domain stop joining automatically, but existing members keep their access. You can claim the domain again later.
+
+## Domains and single sign-on
+
+A verified domain is also required for [single sign-on](/docs/ai/organization/sso/). To have your team sign in through your identity provider, verify the domain first, then set up SSO. The Single sign-on card sits on this page, below your domains.
+
+## Related
+
+- [Single sign-on (SSO)](/docs/ai/organization/sso/) — sign in through your identity provider.
+- [Members & seats](/docs/ai/organization/members/) — seats and the awaiting-a-seat queue.
diff --git a/docs/ai_builder/organization/members.md b/docs/ai_builder/organization/members.md
new file mode 100644
index 00000000000..43589182344
--- /dev/null
+++ b/docs/ai_builder/organization/members.md
@@ -0,0 +1,89 @@
+---
+tags: Organization
+description: Add people to a Reflex organization, manage invitations, and understand how seats are counted.
+---
+
+# Members & Seats
+
+```python exec
+import reflex as rx
+```
+
+An organization's **members** are the people who can work in it. Once someone is a member, you can add them to specific projects.
+
+Manage members under your organization's **Settings → Team** tab.
+
+## Seats
+
+Each member uses one **seat**. A pending invitation also holds a seat until the person joins or you revoke it.
+
+The Members tab shows how many seats are in use, such as *4 of 10 seats used*. When seats run out, remove a member, revoke an invitation, or add seats to your plan.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/members/members_list.webp",
+    alt="The organization Members tab showing the seat counter and a list of members with their roles",
+    class_name="rounded-md h-auto",
+)
+```
+
+```md alert info
+# Seats and billing
+Your seat count is part of your plan; see [Billing](/docs/hosting/billing/) to review or change it. If you're out of seats or don't see the option to add members, [contact sales](https://reflex.dev/pricing/).
+```
+
+## Adding a member
+
+Select **Add member**, enter an email address, and choose the [organization role](/docs/ai/organization/roles-and-permissions/) the person should have.
+
+- If they already have a Reflex account, they're added right away.
+- If they don't, Reflex emails them an invitation, and they join once they sign up.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/members/add_member_dialog.webp",
+    alt="The Add member dialog with fields for an email address and an organization role",
+    class_name="rounded-md h-auto",
+)
+```
+
+```md alert info
+# Organization membership is not project access
+Adding someone to the organization doesn't give them access to any project. Grant that separately from each project's settings. See [Managing project access](/docs/ai/organization/project-access/).
+```
+
+## Pending invitations
+
+Invited people who haven't joined appear under **Pending invitations**, with the role they'll receive. Each pending invitation holds a seat until it's accepted.
+
+To withdraw an invitation, select it and choose **Revoke**. You can re-invite the person later.
+
+## Awaiting a seat
+
+With [verified domains](/docs/ai/organization/domains/), people whose email matches your domain join automatically. If the organization is out of seats when that happens, they go into an **Awaiting a seat** queue.
+
+Queued people hold no seat and have no access. When a seat frees up, select **Activate** to admit them.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/members/awaiting_seat.webp",
+    alt="The Awaiting a seat section listing a user who joined by verified domain, with an Activate button",
+    class_name="rounded-md h-auto",
+)
+```
+
+## Changing a member's role
+
+A member's **organization role** appears next to their name. Pick a new role from the dropdown to change it. See [Roles & permissions](/docs/ai/organization/roles-and-permissions/) for what each role can do.
+
+You can't change your own role; ask another admin if it needs to change.
+
+## Removing a member
+
+Select the delete icon next to a member and confirm. They lose access to the organization and all of its projects. You can add them back later.
+
+## Related
+
+- [Roles & permissions](/docs/ai/organization/roles-and-permissions/) — what each role can do.
+- [Managing project access](/docs/ai/organization/project-access/) — add members to projects.
+- [Verified domains & auto-join](/docs/ai/organization/domains/) — automatic joining by email domain.
diff --git a/docs/ai_builder/organization/moving_projects_and_apps.md b/docs/ai_builder/organization/moving_projects_and_apps.md
new file mode 100644
index 00000000000..909da5f559f
--- /dev/null
+++ b/docs/ai_builder/organization/moving_projects_and_apps.md
@@ -0,0 +1,67 @@
+---
+tags: Organization
+description: Move a Reflex project to another organization, or move an app to another project, as your team's structure changes.
+---
+
+# Moving Projects & Apps
+
+```python exec
+import reflex as rx
+```
+
+Reflex lets you move work as your team's structure changes: transfer a project to another organization, or move an app to another project.
+
+## Moving a project to another organization
+
+You can transfer a whole project, including its apps and settings, from one organization to another. This is useful when a project outgrows a personal organization or moves between teams.
+
+Open the project's **Settings → General** and find the **Move project** card. Choose the destination organization and confirm.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/moving/move_project.webp",
+    alt="The Move project dialog with a dropdown to select a destination organization and a warning about members losing access",
+    class_name="rounded-md h-auto",
+)
+```
+
+### What you need
+
+You must be an **admin of both organizations**: the current one and the destination. If you can't move a project, the card explains why:
+
+- You're not an admin of the project's current organization, or
+- You aren't an admin of any other organization to move it into.
+
+### What happens to members
+
+A project's members come from its current organization. When you move it, **members who aren't in the destination organization lose access.** Reflex lists those people before you confirm. To keep someone's access, add them to the destination organization first.
+
+```md alert warning
+# Check who loses access before moving
+Moving a project isn't undone automatically; you'd have to move it back. Review who loses access before confirming, and add anyone who should keep it to the destination organization first.
+```
+
+## Moving an app to another project
+
+You can move an app from one project to another **within the same organization**, for example to group it with related apps.
+
+In Reflex Build, open the app's options menu (the **⋯** menu on the app), choose **Move app**, and pick the destination project.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/moving/move_app.webp",
+    alt="The Move app dialog listing other projects in the same organization to move the app into",
+    class_name="rounded-md h-auto",
+)
+```
+
+Notes:
+
+- You can only move an app within the same organization. To move it across organizations, move the whole project instead.
+- You need permission to **create apps** in the destination project.
+- Integrations are connected per project, so you may need to reconnect them in the destination project after the move.
+
+## Related
+
+- [Managing project access](/docs/ai/organization/project-access/) — add members to a project before moving it.
+- [Members & seats](/docs/ai/organization/members/) — add people to the destination organization.
diff --git a/docs/ai_builder/organization/overview.md b/docs/ai_builder/organization/overview.md
new file mode 100644
index 00000000000..ca930fe975e
--- /dev/null
+++ b/docs/ai_builder/organization/overview.md
@@ -0,0 +1,115 @@
+---
+tags: Organization
+description: How organizations work in Reflex, and the projects, apps, members, roles, billing, and credits they contain.
+---
+
+# Organizations
+
+```python exec
+import reflex as rx
+```
+
+An **organization** is a shared workspace in Reflex. It contains your projects and their apps, the people who work on them, the roles that control what each person can do, and your billing and credits.
+
+Every project and app belongs to an organization, in both [Reflex Build](/docs/ai/overview/what-is-reflex-build/) and [Reflex Cloud](/docs/hosting/deploy-quick-start/). Your account starts with one, created the first time you sign in.
+
+## Organizations, projects, and apps
+
+Reflex has three levels.
+
+```python eval
+rx.image(
+    src=rx.color_mode_cond(
+        "https://web.reflex-assets.dev/docs-preview/organization/overview/hierarchy.webp",
+        "https://web.reflex-assets.dev/docs-preview/organization/overview/hierarchy_dark.webp",
+    ),
+    alt="Diagram showing an organization containing projects, and each project containing apps",
+    class_name="rounded-md h-auto",
+)
+```
+
+- **Organization**: the top level, usually one per company or team. Members, seats, billing, credits, verified domains, and single sign-on are set here.
+- **Project**: a group of related apps within an organization, with its own members, roles, and settings. Teams commonly use one project per product or client.
+- **App**: an application you build and deploy. Each app belongs to a project.
+
+People join the organization first, then get access to individual projects. This keeps one workspace usable for a large team without giving everyone access to everything in it.
+
+## Where settings live
+
+Settings live at either the organization or the project level.
+
+| Organization level | Project level |
+| --- | --- |
+| Members and seats | Which members can open the project |
+| Organization roles (Admin, Manager, Member) | Project roles (Viewer, Editor, Admin, and custom roles) |
+| Billing, credits, and spending limits | Project name and deletion |
+| Verified domains and auto-join | Deployment approvals |
+| Single sign-on (SSO) | Secrets and integrations |
+| Connected cloud providers | Project activity (audit log) |
+| Organization-wide activity (audit log) | Apps and deployments |
+
+## Creating an organization
+
+Most teams need only one organization. Create a second when you want fully separate members, billing, and projects, for example to keep two companies or clients apart.
+
+Open the **organization switcher** at the top of the page, choose **Create organization**, name it, and confirm.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/overview/create_organization.webp",
+    alt="The organization switcher menu open, with the Create organization option highlighted",
+    class_name="rounded-md h-auto",
+)
+```
+
+```md alert info
+# Creating organizations depends on your plan
+If you don't see the option to create one, it isn't included in your current plan. [Contact sales](https://reflex.dev/pricing/) to learn more.
+```
+
+## Switching organizations
+
+If you belong to more than one organization, use the **organization switcher** to move between them. The projects, members, billing, and settings you see always belong to the selected organization. If a project or teammate appears to be missing, check that the right organization is selected.
+
+## Name and ID
+
+The **General** tab of your organization's settings shows two fields:
+
+- **Organization name**: the display name used throughout Reflex. Admins can change it at any time.
+- **Organization ID**: a fixed identifier used by the CLI and API. You can copy it, but not change it.
+
+## Deleting an organization
+
+Deleting an organization is permanent and removes every project inside it.
+
+Open **Settings → General** and use **Delete organization**. You'll be asked to type the organization's name to confirm.
+
+```md alert warning
+# You can't delete your only organization
+Reflex won't delete an organization if it's the only one you belong to. Create or join another first.
+```
+
+## Plans
+
+Verified domains, single sign-on, bring-your-own-cloud, and inviting teammates are Enterprise features, and your seat count depends on your plan. When a feature isn't part of your plan, Reflex shows a note with a link to [contact sales](https://reflex.dev/pricing/).
+
+## In this section
+
+Getting your team in:
+
+- [Members & seats](/docs/ai/organization/members/) — add people and manage seats.
+- [Verified domains & auto-join](/docs/ai/organization/domains/) — let teammates join by email domain.
+- [Single sign-on (SSO)](/docs/ai/organization/sso/) — sign in through your identity provider.
+
+Controlling access:
+
+- [Roles & permissions](/docs/ai/organization/roles-and-permissions/) — what each organization and project role can do.
+- [Managing project access](/docs/ai/organization/project-access/) — add members to specific projects.
+- [Custom roles](/docs/ai/organization/custom-roles/) — define a role with the exact permissions you need.
+
+Governing and organizing:
+
+- [Deployment approvals](/docs/ai/organization/deployment-approvals/) — require sign-off before a deployment runs.
+- [Audit logs](/docs/ai/organization/audit-logs/) — review who did what.
+- [Moving projects & apps](/docs/ai/organization/moving-projects-and-apps/) — move work between projects and organizations.
+- [Bring your own cloud](/docs/ai/organization/cloud-providers/) — run apps on your own infrastructure.
diff --git a/docs/ai_builder/organization/project_access.md b/docs/ai_builder/organization/project_access.md
new file mode 100644
index 00000000000..6a41cefbf60
--- /dev/null
+++ b/docs/ai_builder/organization/project_access.md
@@ -0,0 +1,75 @@
+---
+tags: Organization
+description: Give organization members access to specific Reflex projects and assign each person a project role.
+---
+
+# Managing Project Access
+
+```python exec
+import reflex as rx
+```
+
+Organization membership lets someone join projects, but not any specific one. You control access per project: who can open it and what they can do.
+
+Manage this under each project's **Settings → Members** tab.
+
+## Who already has access
+
+Some people have access without being added:
+
+- **Organization admins** can open every project. They show an **Organization admin** badge in the member list, and their access can't be changed here because it comes from their organization role.
+- **Managers and members** have no access to a project until you add them.
+
+## Adding members to a project
+
+Select **Add user** to open the member picker. It lists organization members who aren't on the project yet. Choose one or more, assign each a [project role](/docs/ai/organization/roles-and-permissions/), and select **Add to project**.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/project-access/add_project_members.webp",
+    alt="The Add project members dialog showing selectable organization members and a role dropdown for each",
+    class_name="rounded-md h-auto",
+)
+```
+
+You can only add people who already belong to your organization. If someone isn't in the list, they aren't a member yet.
+
+```md alert info
+# Can't find someone?
+They need to join the organization first. If you're an admin, add them under the organization's **Settings → Team** (see [Members & seats](/docs/ai/organization/members/)); otherwise, ask an admin to add them.
+```
+
+## Changing a member's project role
+
+Each member has a role dropdown next to their name. Pick a new role to change their access.
+
+Two cases can't be edited here:
+
+- **Your own role**, so you can't lock yourself out.
+- **Organization admins**, whose access is inherited from the organization.
+
+Assigning project roles requires the project **Admin** role or organization admin.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/project-access/project_member_roles.webp",
+    alt="A project member list with a role dropdown open, and an organization admin shown with a non-editable badge",
+    class_name="rounded-md h-auto",
+)
+```
+
+## Removing a member from a project
+
+Select the delete icon next to a member and confirm. They lose access to this project but remain in the organization and keep access to their other projects.
+
+To remove someone from the organization entirely, use the organization's Members tab instead (see [Members & seats](/docs/ai/organization/members/)).
+
+```md alert info
+# Inviting teammates is an Enterprise feature
+Collaborating with teammates on projects is part of the Enterprise plan. If you don't see the option to add members, [contact sales](https://reflex.dev/pricing/).
+```
+
+## Related
+
+- [Roles & permissions](/docs/ai/organization/roles-and-permissions/) — what each project role can do.
+- [Custom roles](/docs/ai/organization/custom-roles/) — define a role with specific permissions.
diff --git a/docs/ai_builder/organization/roles_and_permissions.md b/docs/ai_builder/organization/roles_and_permissions.md
new file mode 100644
index 00000000000..1b8650661d5
--- /dev/null
+++ b/docs/ai_builder/organization/roles_and_permissions.md
@@ -0,0 +1,111 @@
+---
+tags: Organization
+description: How Reflex roles and permissions work at the organization and project level, and which role to give each person.
+---
+
+# Roles & Permissions
+
+```python exec
+import reflex as rx
+```
+
+Roles decide what each person can do. Reflex has two levels of roles:
+
+- **Organization roles** apply across the whole organization: managing members, billing, and creating projects.
+- **Project roles** apply within a single project: building apps, editing secrets, and approving deployments.
+
+The two are assigned separately. Organization roles govern running the organization; project roles govern the work done inside a project.
+
+## Organization roles
+
+Every member has one organization role.
+
+| | **Member** | **Manager** | **Admin** |
+| --- | :---: | :---: | :---: |
+| Belong to the organization and use the projects they're added to | ✓ | ✓ | ✓ |
+| Create new projects | | ✓ | ✓ |
+| View the organization audit log | | ✓ | ✓ |
+| Add and remove members, change roles | | | ✓ |
+| Rename or delete the organization | | | ✓ |
+| Manage billing, seats, and credits | | | ✓ |
+| Verify domains and configure single sign-on | | | ✓ |
+| Connect cloud providers | | | ✓ |
+| Automatically an **Admin** of every project | | | ✓ |
+
+- **Member**: has access only to the projects they're added to, with the project role they're given there.
+- **Manager**: a member who can also create projects. Suited to team leads who don't manage people or billing.
+- **Admin**: manages members and billing, and is an admin of every project in the organization.
+
+```md alert info
+# Organization admins have access to every project
+An organization admin is a project admin everywhere, so you don't add them to projects individually. They appear in a project's member list with an **Organization admin** badge, and their access can't be edited there.
+```
+
+## Project roles
+
+When you add a member to a project, you assign a **project role**. Reflex has three built-in roles, plus [custom roles](/docs/ai/organization/custom-roles/) for cases the built-ins don't cover.
+
+| | **Viewer** | **Editor** | **Admin** |
+| --- | :---: | :---: | :---: |
+| View the project, its apps, and activity | ✓ | ✓ | ✓ |
+| Create apps | | ✓ | ✓ |
+| Create threads (Build chats) | | ✓ | ✓ |
+| See that secrets exist (view names) | | ✓ | ✓ |
+| Reveal secret values | | | ✓ |
+| Add and edit secrets | | | ✓ |
+| Manage integrations | | | ✓ |
+| Approve deployments | | | ✓ |
+| View the project audit log | | | ✓ |
+| Rename the project | | | ✓ |
+| Delete the project | | | ✓ |
+| Add and remove project members, assign roles | | | ✓ |
+| Create and edit custom roles | | | ✓ |
+
+- **Viewer**: read-only. Can see the project and its apps but can't edit, deploy, or reveal secret values.
+- **Editor**: creates and edits apps, works in Build, and manages app secrets. Can see that project secrets exist but not reveal their values.
+- **Admin**: full control of the project, including members, roles, integrations, secrets, approvals, and deletion.
+
+## How the two levels combine
+
+A person's access to a project comes from either their organization role or their project role:
+
+- **Organization admins** are admins of every project automatically; you don't add them.
+- **Managers and members** have no project access until you add them to a project and assign a role. See [Managing project access](/docs/ai/organization/project-access/).
+- Changing someone's project role doesn't change their organization role, and the reverse is also true.
+
+```python eval
+rx.image(
+    src=rx.color_mode_cond(
+        "https://web.reflex-assets.dev/docs-preview/organization/roles-and-permissions/roles_overview.webp",
+        "https://web.reflex-assets.dev/docs-preview/organization/roles-and-permissions/roles_overview_dark.webp",
+    ),
+    alt="Diagram showing organization roles on the left and project roles on the right, with an organization admin inheriting project admin across all projects",
+    class_name="rounded-md h-auto",
+)
+```
+
+## Choosing a role
+
+Guidelines for most teams:
+
+- Give organization **Admin** only to the few people who manage the team and its billing.
+- Use **Manager** for team leads who create projects but shouldn't manage people or billing.
+- Keep most people as **Member** and control their access project by project.
+- Within a project, make builders **Editors**, reserve **Admin** for project owners, and use **Viewer** for anyone who only needs to view.
+- When a built-in project role is close but not exact, create a [custom role](/docs/ai/organization/custom-roles/) rather than over-granting Admin.
+
+## Permission reference
+
+The built-in project roles are combinations of individual permissions, which you can also assemble into a [custom role](/docs/ai/organization/custom-roles/). Reflex groups them as:
+
+- **Project:** Create apps, Create threads, Rename project, Delete project.
+- **Secrets & integrations:** Manage integrations, View secret names, Reveal secret values, Edit secrets.
+- **Deployments:** Approve deployments.
+- **Activity:** View audit log.
+
+**Managing members** and **managing roles** can't be granted on their own. Either one amounts to admin control, so both stay with the Admin role. Billing permissions come from your organization role, not from project roles.
+
+## Related
+
+- [Managing project access](/docs/ai/organization/project-access/) — add members to a project and assign roles.
+- [Custom roles](/docs/ai/organization/custom-roles/) — define a role with specific permissions.
diff --git a/docs/ai_builder/organization/sso.md b/docs/ai_builder/organization/sso.md
new file mode 100644
index 00000000000..1904e8de894
--- /dev/null
+++ b/docs/ai_builder/organization/sso.md
@@ -0,0 +1,54 @@
+---
+tags: Organization
+description: Set up single sign-on (SSO) so your team signs in to Reflex through your company identity provider using SAML or OIDC.
+---
+
+# Single Sign-On (SSO)
+
+```python exec
+import reflex as rx
+```
+
+**Single sign-on (SSO)** lets your team sign in to Reflex through your company's identity provider, using the same login as your other work tools. People don't manage separate Reflex credentials, and your IT team controls access from one place.
+
+Reflex supports **SAML** and **OIDC**, so it works with providers such as Okta, Microsoft Entra ID, and Google Workspace. SSO is set up on the **Domains** page (Settings → Domains), where it appears as a Single sign-on card once a domain is verified. It's part of the **Enterprise** plan.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/sso/sso_card.webp",
+    alt="The Single sign-on settings card showing an Enable SSO button and status badge",
+    class_name="rounded-md h-auto",
+)
+```
+
+## Before you begin
+
+SSO requires a [verified domain](/docs/ai/organization/domains/). Reflex uses the domain to route the right sign-ins to your provider, so verify it first.
+
+## Setting up SSO
+
+1. Verify your domain (see [Verified domains & auto-join](/docs/ai/organization/domains/)).
+2. On the Domains page, find the **Single sign-on** card and select **Enable SSO**.
+3. Select **Configure identity provider** and follow the steps to connect your provider and exchange configuration details.
+
+Once configured, the card shows an **Enabled** badge, and members on your verified domain sign in through your provider.
+
+```md alert info
+# Who can set up SSO
+Only organization admins can enable, configure, or disable single sign-on.
+```
+
+## How members sign in
+
+With SSO enabled, people on your verified domain are sent to your provider to sign in. Access is governed there, so removing someone in your provider also removes their access to Reflex.
+
+## Disabling SSO
+
+Use **Disable** on the Single sign-on card. Members go back to signing in with their usual method, and your provider configuration is removed from Reflex.
+
+Disabling SSO doesn't remove anyone; existing members keep their access. You can disable SSO even after a plan change, so your organization is never locked into a provider.
+
+## Related
+
+- [Verified domains & auto-join](/docs/ai/organization/domains/) — the prerequisite for SSO.
+- [Members & seats](/docs/ai/organization/members/) — manage who belongs to the organization.
diff --git a/docs/app/reflex_docs/templates/docpage/sidebar/sidebar_items/ai.py b/docs/app/reflex_docs/templates/docpage/sidebar/sidebar_items/ai.py
index 09c6b287673..883523f49e6 100644
--- a/docs/app/reflex_docs/templates/docpage/sidebar/sidebar_items/ai.py
+++ b/docs/app/reflex_docs/templates/docpage/sidebar/sidebar_items/ai.py
@@ -44,6 +44,22 @@ def get_sidebar_items_ai_builder_overview():
                 ai_builder.app_lifecycle.share_app,
             ],
         ),
+        create_item(
+            "Organization",
+            children=[
+                ai_builder.organization.overview,
+                ai_builder.organization.members,
+                ai_builder.organization.roles_and_permissions,
+                ai_builder.organization.project_access,
+                ai_builder.organization.custom_roles,
+                ai_builder.organization.domains,
+                ai_builder.organization.sso,
+                ai_builder.organization.deployment_approvals,
+                ai_builder.organization.audit_logs,
+                ai_builder.organization.moving_projects_and_apps,
+                ai_builder.organization.cloud_providers,
+            ],
+        ),
         # create_item(
         #     "Integrations",
         #     children=[
diff --git a/docs/app/reflex_docs/templates/docpage/sidebar/sidebar_items/item.py b/docs/app/reflex_docs/templates/docpage/sidebar/sidebar_items/item.py
index 4c70332b5e3..223aca0643c 100644
--- a/docs/app/reflex_docs/templates/docpage/sidebar/sidebar_items/item.py
+++ b/docs/app/reflex_docs/templates/docpage/sidebar/sidebar_items/item.py
@@ -20,6 +20,7 @@ def create_item(route: Route, children=None):
             "Mcp": "MCP",
             "Ai": "AI",
             "Gcp": "GCP",
+            "Sso": "SSO",
         }
         name = re.sub(
             r"\b(" + "|".join(acronyms.keys()) + r")\b",
diff --git a/docs/hosting/adding-members.md b/docs/hosting/adding-members.md
index 0c614376740..855f50a1c0d 100644
--- a/docs/hosting/adding-members.md
+++ b/docs/hosting/adding-members.md
@@ -8,6 +8,11 @@ A project is a collection of applications (apps / websites).
 
 Every project has its own billing page that are accessible to Admins.
 
+```md alert info
+# Looking for members, roles, and permissions?
+People, seats, roles, and access are organized at the organization and project level. For the complete guide, see [Organizations](/docs/ai/organization/overview/) — in particular [Members & seats](/docs/ai/organization/members/), [Roles & permissions](/docs/ai/organization/roles-and-permissions/), and [Managing project access](/docs/ai/organization/project-access/).
+```
+
 
 
 ## Adding Team Members
diff --git a/docs/hosting/billing.md b/docs/hosting/billing.md
index abde86eef8c..0b5265d204b 100644
--- a/docs/hosting/billing.md
+++ b/docs/hosting/billing.md
@@ -4,6 +4,11 @@ import reflex as rx
 
 # Billing
 
+```md alert info
+# Members, seats, and roles
+Seats, members, and roles are managed in your organization's settings. See [Members & seats](/docs/ai/organization/members/) and [Roles & permissions](/docs/ai/organization/roles-and-permissions/) in the [Organizations](/docs/ai/organization/overview/) section.
+```
+
 ## Overview 
 
 Billing for Reflex Cloud is monthly per project. Project owners and admins are able to view and manage the billing page. 

From 7b0c553975568c960eb60e5e8c2498f780339b20 Mon Sep 17 00:00:00 2001
From: Khaleel Al-Adhami <khaleel.aladhami@gmail.com>
Date: Tue, 21 Jul 2026 16:19:57 -0700
Subject: [PATCH 2/2] use explicit kwargs with color_mode_cond

Co-authored-by: Masen Furer <m_github@0x26.net>
---
 docs/ai_builder/organization/roles_and_permissions.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/ai_builder/organization/roles_and_permissions.md b/docs/ai_builder/organization/roles_and_permissions.md
index 1b8650661d5..5e0939bf089 100644
--- a/docs/ai_builder/organization/roles_and_permissions.md
+++ b/docs/ai_builder/organization/roles_and_permissions.md
@@ -76,8 +76,8 @@ A person's access to a project comes from either their organization role or thei
 ```python eval
 rx.image(
     src=rx.color_mode_cond(
-        "https://web.reflex-assets.dev/docs-preview/organization/roles-and-permissions/roles_overview.webp",
-        "https://web.reflex-assets.dev/docs-preview/organization/roles-and-permissions/roles_overview_dark.webp",
+        light="https://web.reflex-assets.dev/docs-preview/organization/roles-and-permissions/roles_overview.webp",
+        dark="https://web.reflex-assets.dev/docs-preview/organization/roles-and-permissions/roles_overview_dark.webp",
     ),
     alt="Diagram showing organization roles on the left and project roles on the right, with an organization admin inheriting project admin across all projects",
     class_name="rounded-md h-auto",