> ## Documentation Index
> Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizations and roles

> How tenants, organizations, and roles decide what each person and API key can see and do in Managed Agents.

Everything you create in Managed Agents belongs to one organization, and your role decides what you can do there. This page explains the model, so you can predict exactly what a person or an API key can reach.

## Tenants and organizations

* **Tenant.** The top level of an account. The first time you sign in, Recursion creates a tenant for you and makes you its **primary owner**.
* **Organization.** A separate space inside a tenant. Agents, environments, sessions, vaults, skills, and tags each belong to exactly one organization and are never visible from another.
* **Default organization.** Every tenant has one, named **Default**. Every member of the tenant can reach it, so it has no member list of its own.
* **Other organizations.** Tenant admins and owners create more under **Settings › Organizations**, up to 100 active ones per tenant, and add tenant members to each with a role.

The console works in one organization at a time. Pick it from the organization menu at the top of the sidebar. API keys follow the same model: an organization-scoped key works in its own organization, and a tenant-scoped key names one with `x-organization-id`, using an organization id or `default`. See [API keys](/recursion/api-keys).

## Roles at a glance

Each member has one **tenant role**. It decides what they can do in the Default organization and across the tenant:

* **User** views agents, sessions, and their results, and creates their own API keys.
* **Developer** builds and runs agents: everything a User can do, plus creating, changing, and deleting them. A Developer doesn't manage people or tenant settings.
* **Billing** pays for the tenant: credits, cards, and invoices. A Billing member's console shows **Billing** and **Settings**, with no Managed Agents access.
* **Admin** runs the tenant: everything a Developer can do, plus members, organizations, tenant settings, Domains, Enterprise SSO, Billing, and the audit log.
* **Owner** is an Admin who can also manage other Admins and Owners.
* **Primary owner** is the one Owner the tenant was created for, and the only person who can transfer ownership.

In other organizations an admin can give a member a different role there; see [Roles in each organization](#roles-in-each-organization).

## What each role can do

| Task | User | Developer | Billing | Admin or Owner |
| - | :-: | :-: | :-: | :-: |
| **Managed Agents** | | | | |
| View agents and sessions | ✓ | ✓ | – | ✓ |
| Build and run agents | – | ✓ | – | ✓ |
| Connect integrations | – | ✓ | – | ✓ |
| Own [API keys](/recursion/api-keys) | ✓ | ✓ | – | ✓ |
| **People and organizations** | | | | |
| Invite and manage members | – | – | – | ✓ |
| Manage Admins and Owners | – | – | – | Owner only |
| Organizations | – | – | – | ✓ |
| **Tenant settings** | | | | |
| Rename the tenant and require multi-factor authentication | – | – | – | ✓ |
| [Domains](/recursion/domains) | – | – | – | ✓ |
| [Enterprise SSO](/recursion/enterprise-sso) | – | – | – | ✓ |
| [Billing](/recursion/billing) | – | – | ✓ | ✓ |
| [Audit log](/recursion/console) | – | – | – | ✓ |

**Build and run agents** means creating, changing, and deleting agents, environments, vaults, and skills, and starting sessions. **Invite and manage members** covers User, Developer, and Billing members; only Owners and the primary owner manage Admins and Owners.

The Managed Agents rows apply in the Default organization. In other organizations, the role you have there decides them; see [Roles in each organization](#roles-in-each-organization).

The primary owner is the person the tenant was created for, until they transfer ownership. There's exactly one, and nobody can remove or demote them, including themselves. On **Members**, they can transfer ownership to another member. They become an owner, and that member becomes the primary owner. The page warns them first: they cannot undo it, and only the new primary owner can transfer it again.

## Roles in each organization

Your role in each organization comes from your tenant role:

| Tenant role | In the Default organization | In other organizations |
| - | - | - |
| **User** | Organization user | The role an admin gave them there, or no access |
| **Developer** | Organization developer | The role an admin gave them there, or no access |
| **Billing** | Organization billing | Organization billing, or Organization admin if an admin made them one |
| **Admin**, **Owner**, **Primary owner** | Organization admin | Organization admin |

An Organization admin can do everything an Organization developer can, and also manages that organization's members. An Organization user can only read, and an Organization billing member has no Managed Agents access.

<Accordion title="What read and create cover">
  * **Read** covers listing and viewing agents, sessions, transcripts, events, environments, vaults (never secret values), cost, and [Analytics](/recursion/analytics).
  * **Create** covers creating resources and starting sessions. Testing an environment's setup script also needs create, because it provisions compute.
  * **Testing a connection needs create too.** Testing an MCP server (the server's test in the console, or `probeMcpServer`) and **Test connection** on an integration are open to Organization developers and admins, not to Organization users.
</Accordion>

The role is checked on every request, for people in the console and for API keys alike. A request your role doesn't allow returns `403 forbidden`. A request for an organization you can't reach returns `404 not_found`, so its existence isn't revealed.

## What can go wrong

The most common problems:

* **`403 forbidden` on create, update, or delete.** The role is **Organization user**, which can only read. Use an account or key with the developer or admin role.
* **`403 forbidden` on every Managed Agents request.** The role is **Organization billing**, which has no Managed Agents access. Use an account or key with the user, developer, or admin role.
* **`404 not_found` naming an organization.** The `x-organization-id` header names an organization you can't reach, an archived one, or a different one than an organization-scoped key's. Send an organization you belong to, or `default`, or omit the header for an organization-scoped key. See [API keys](/recursion/api-keys).

<Accordion title="Every role and organization error">
  | Code or symptom | Cause | Fix |
  | - | - | - |
  | `403 forbidden` on create, update, or delete | The role is **Organization user**, which can only read. | Use an account or key with the developer or admin role. |
  | An MCP server test says **Testing requires create access.** | The role is **Organization user**. | Ask an Organization developer or admin to run the test, or to change your role. |
  | `403 forbidden` on every Managed Agents request | The role is **Organization billing**, which has no Managed Agents access. | Use an account or key with the user, developer, or admin role. |
  | `404 not_found` naming an organization | The `x-organization-id` header names an organization you can't reach, an archived one, or a different organization than an organization-scoped key's. | Send an organization you belong to, or `default`, or omit the header for an organization-scoped key. See [API keys](/recursion/api-keys). |
</Accordion>

## Next steps

<CardGroup cols={2}>
  <Card title="API keys" href="/recursion/api-keys">
    Create a key scoped to one organization or the whole tenant.
  </Card>

  <Card title="Billing" href="/recursion/billing">
    Buy prepaid credits and manage cards.
  </Card>

  <Card title="Security" href="/recursion/security">
    See how organizations, sandboxes, and credentials are isolated.
  </Card>

  <Card title="Console" href="/recursion/console">
    Find the screen for each task.
  </Card>
</CardGroup>