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

# Roles and permissions

> What each role in an Opper organization can do, which plans can assign roles, and how to invite a member with a role or change it later.

Every member of an Opper organization has one role. The role decides what the
member can see and do in the Opper platform and with the API keys they own.

Any member can see their own role, and the role of every other member, under
**Settings**, then **Users**.

## Built-in roles

Opper has four built-in roles. Each role includes everything the role before it
can do.

| Role | Summary |
| - | - |
| **Viewer** | Read-only. Can look at the organization's projects and usage. Cannot run models or change settings. |
| **Developer** | Can do what a Viewer can, and also run models, configure dynamic routes, manage their own API keys and view rules. |
| **Admin** | Can do what a Developer can, and also manage the organization: its projects, rules, members, keys and billing. |
| **Owner** | Can do what an Admin can, and also transfer ownership and delete the organization. |

## What each role can do

### Workspace

| Resource | Permission | Viewer | Developer | Admin | Owner |
| - | - | - | - | - | - |
| Projects | View projects | Yes | Yes | Yes | Yes |
| Projects | Create, edit and delete projects | No | No | Yes | Yes |
| Dynamic routes | Inspect dynamic routes | Yes | Yes | Yes | Yes |
| Dynamic routes | Configure dynamic routes | No | Yes | Yes | Yes |
| Models & route execution | Run models and routes | No | Yes | Yes | Yes |
| Personal API keys | Manage own API keys | No | Yes | Yes | Yes |
| Project API keys | Manage project API keys | No | No | Yes | Yes |

**Run models and routes** covers calls made with the member's API keys and
calls made in the playground.

**Configure dynamic routes** covers everything that changes a
[dynamic route](/capabilities/routes/overview): creating, editing, deploying,
rolling back and deleting it.

### Observability & governance

| Resource | Permission | Viewer | Developer | Admin | Owner |
| - | - | - | - | - | - |
| Usage | View usage | Yes | Yes | Yes | Yes |
| Trace metadata | View trace metadata | Yes | Yes | Yes | Yes |
| Trace inputs & outputs | View trace inputs and outputs | No | No | Yes | Yes |
| Rules | View rules | No | Yes | Yes | Yes |
| Rules | Configure rules | No | No | Yes | Yes |
| Audit logs | View audit logs | No | No | Yes | Yes |

A member with **View trace metadata** but without **View trace inputs and
outputs** can open [Traces](/control-plane/trace) and [Logs](/control-plane/logs),
but does not see prompts, responses or other captured content.

### Organization

| Resource | Permission | Viewer | Developer | Admin | Owner |
| - | - | - | - | - | - |
| Members | Manage members and assign roles | No | No | Yes | Yes |
| Roles & permissions | Create and edit roles | No | No | Yes | Yes |
| SSO group mappings | Map SSO groups | No | No | Yes | Yes |
| Single sign-on setup | Set up and enforce single sign-on | No | No | Yes | Yes |
| Management credentials | Manage management credentials | No | No | Yes | Yes |
| Billing & plans | View billing | No | No | Yes | Yes |
| Billing & plans | Manage billing and plans | No | No | Yes | Yes |
| Ownership | Transfer ownership | No | No | No | Yes |
| Organization | Delete the organization | No | No | No | Yes |

Management credentials are the management keys used with the
[Management API](/control-plane/management-api).

<Note>
  **View billing** decides whether the organization's balance, spend and budget
  are included when one of the member's API keys calls `GET /v3/me`. In the
  platform, every member can open **Settings**, then **Billing & Credits**, and
  see the balance, spend and recent activity. Only a role with **Manage billing
  and plans** can add credit, change auto-recharge or change the plan.
</Note>

A role gives access to a feature only when the organization's plan includes
that feature. For example, setting up single sign-on requires the Enterprise
plan.

## Who can view and change rules

* **View rules:** Owner, Admin and Developer. Viewer cannot view rules.
* **Change rules:** Owner and Admin. Developer and Viewer cannot change rules.

In the tables above, changing rules is the **Configure rules** permission. On
Enterprise, a [custom role](#custom-roles) can hold either permission. For
example, an Enterprise organization can create a role that can run models but
cannot view rules.

A member whose role can view rules but cannot change them sees the
[Rules](/control-plane/rules/overview) page marked **Read only**. Every field
on the page is disabled.

A member whose role cannot view rules:

* Does not see the **Rules** link under **Observe & Control** in the sidebar.
* Sees a panel titled **Rules are managed by your administrators** in place of
  the Rules page, and in place of the **Effective policy** section on the
  dashboard.

The organization's rules apply to every member's calls, whether or not the
member can view them.

If you need more access to rules than your role gives you, ask an Owner or
Admin of your organization to [change your role](#change-a-role).

Rules can also be read and changed through the
[Management API](/control-plane/management-api#manage-rules-from-code) by
anyone who holds a management key with the matching scope. Only a member whose
role holds **Manage management credentials** can create management keys.

## Which plans can choose roles

| Plan | Roles you can assign |
| - | - |
| **Control Plane** | Admin, Developer or Viewer. You choose the role when you invite a member and can change it later. |
| **Enterprise** | Admin, Developer or Viewer, plus your own custom roles. You choose the role when you invite a member and can change it later. |
| **All other plans** | None. Every invited member joins as an Admin, and a member's role cannot be changed. |

### Custom roles

Custom roles are available on the Enterprise plan only.

A custom role can hold any subset of the permissions an Admin holds. It can
never hold the two Owner-only permissions: **Transfer ownership** and **Delete
the organization**.

Use a custom role when a built-in role holds more than you want a member to
have. For example, a custom role can run models without being able to
configure dynamic routes.

To create one, your role must hold **Create and edit roles**. Open
**Settings**, then **Roles & permissions**, and select **Create role**. Enter a
**Role name**, select the permissions the role should hold, and select **Save
role**. You can only grant permissions that your own role holds.

The role editor uses the group, resource and permission names from the tables
above. It lists every permission in those tables except **Set up and enforce
single sign-on** and the two Owner-only permissions.

A custom role is assigned the same way as a built-in role: in the invite
dialog, or in the role dropdown on the **Users** page.

## The Owner

* The person who creates an organization is its Owner.
* An organization has one Owner.
* Owner cannot be chosen in an invitation or in the role dropdown. It moves
  only when the current Owner transfers ownership.
* The Owner cannot leave the organization or be removed from it. Transfer
  ownership first.

### Transfer ownership

Only the Owner can transfer ownership, and only to someone who is already a
member of the organization.

1. Open **Settings**, then **Users**.
2. In the row of the member who should become the Owner, open the actions menu
   and select **Make owner**.
3. Select **Make owner** again to confirm.

The transfer takes effect immediately. You stay a member of the organization,
with a role other than Owner. Check the **Users** page to see which role you
now have.

## Invite a member with a role

To invite members, your role must hold **Manage members and assign roles**
(Owner and Admin do).

1. Open **Settings**, then **Users**.
2. Select **Invite user**.
3. Enter one email address in each row.
4. On Control Plane and Enterprise, choose a role in the **Role** column of
   each row. You can only choose roles whose permissions your own role also
   holds. On all other plans the **Role** column is locked to **Admin**.
5. Check the role shown next to each email address.
6. Select **Send invitations**.

<Warning>
  Check the role next to every email address before you select **Send
  invitations**. Each row has its own role, and the person joins with the role
  their row shows.
</Warning>

Until the person accepts, they appear on the **Users** page as a pending
invite. The **Users** page does not show which role a pending invitation
carries. If you sent an invitation with the wrong role, remove the invitation
and send a new one, or change the role after the person has joined.

Members can also be invited from code. See
[Manage members and invitations](/control-plane/management-api#manage-members-and-invitations)
in the Management API guide.

## Change a role

Changing a member's role requires the Control Plane or Enterprise plan, and a
role that holds **Manage members and assign roles** (Owner and Admin do).

1. Open **Settings**, then **Users**.
2. In the member's row, open the role dropdown.
3. Select the new role.

The change is saved when you select the role, and applies immediately.

If a member's row shows the role as a label with no dropdown, one of these
applies:

* The member is the Owner. Use [Transfer ownership](#transfer-ownership)
  instead.
* The member's role is managed by your identity provider through single
  sign-on. The label shows **SSO** next to the role.
* The member's current role holds a permission that your own role does not
  hold.
* Your organization's plan does not include role choice, or your own role does
  not hold **Manage members and assign roles**.

The dropdown only lists roles whose permissions your own role also holds.

## Permission identifier reference

This section is a reference for Enterprise organizations that use custom
roles. It lists the identifier of each permission in the tables above.

| Identifier | Permission |
| - | - |
| `projects:read` | View projects |
| `projects:write` | Create, edit and delete projects |
| `dynamic_routes:read` | Inspect dynamic routes |
| `dynamic_routes:write` | Configure dynamic routes |
| `inference:execute` | Run models and routes |
| `personal_keys:manage` | Manage own API keys |
| `project_keys:manage` | Manage project API keys |
| `usage:read` | View usage |
| `traces:read` | View trace metadata |
| `traces:content:read` | View trace inputs and outputs |
| `controls:read` | View rules |
| `controls:write` | Configure rules |
| `audit:read` | View audit logs |
| `members:write` | Manage members and assign roles |
| `roles:write` | Create and edit roles |
| `sso:groups:write` | Map SSO groups |
| `sso:write` | Set up and enforce single sign-on |
| `management_keys:write` | Manage management credentials |
| `billing:read` | View billing |
| `billing:write` | Manage billing and plans |
| `ownership:transfer` | Transfer ownership (Owner only) |
| `organization:delete` | Delete the organization (Owner only) |

A custom role that holds **Manage billing and plans** can also view billing.

Management API keys have their own list of
[scopes](/control-plane/management-api#scopes). Some scopes share a
name with a permission above, but a scope limits what a key can do and a
permission limits what a member can do.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.