Organizations and roles

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.

​

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.

​

What each role can do

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. 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: 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.

What read and create cover

• Read covers listing and viewing agents, sessions, transcripts, events, environments, vaults (never secret values), cost, and 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.

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.

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.

​

Next steps