# Roles and permissions

This page is the lookup table for access control: which role grants what, how a permission key is written, and how one call is decided. It governs what a member of your organization may do inside the platform, not who may do what inside the applications you build and deploy — that is your application's own concern.

There are two separate layers, and they answer different questions.

| Layer | The question it answers |
| --- | --- |
| The organization role — `owner`, `admin` or `member` | Who may manage the organization: invite people, change roles, share products, create products. |
| The product grant | What a person may actually do inside one product. An organization role never grants access across products by itself: owners and admins reach every product because a concrete grant is created for them on each one, and a `member` reaches a product only through an explicit share. |

[Understand where grants come from](/access/product-access) covers how a grant appears; this page covers what it contains.

## Organization roles

| Role | What it can do |
| --- | --- |
| Owner | Everything. Rename the organization, change its security policy, read the billing summary, delete the organization, and all admin actions. |
| Admin | Manage members and role definitions, share products with members, create products. Not billing, not organization security. |
| Member | No organization management. Sees only the products explicitly shared with them. |

A membership is `invited` until the person accepts, then `active`. A membership can carry an expiry.

> **Note.** Ownership does not move, and neither does a product. `owner` is one of the roles [`organization_member_invite`](/reference/mcp-tools/organization_member_invite) accepts, so an organization can have more than one owner from the start — but [`organization_member_set-role`](/reference/mcp-tools/organization_member_set-role) accepts only `admin` and `member`, so an existing member can never be raised to owner afterwards. There is no operation that moves a product from one organization to another either. Both arrangements are chosen when the organization is created rather than corrected later, so a builder who expects to hand a product to a client should have the client create the organization on day one.

## Product roles

Inside a product, the platform seeds four immutable system roles. Each role holds two lists of permission patterns: `allow` and `deny`.

| Role | Grants |
| --- | --- |
| Owner | Allows everything. |
| Admin | Allows everything, except billing operations and deleting the product. |
| Member | Allows the operational verbs — create, update, list, get, me, select — and denies role-management changes. |
| Viewer | Allows read-only operations — list, get, me, select — and denies role-management changes. |

Member and Viewer are defined by verb, not by area, so they cover new areas of the platform automatically.

Who may hand out which role:

| The assigner | May assign |
| --- | --- |
| Owner | Any role except owner. [`organization_product_set-access`](/reference/mcp-tools/organization_product_set-access) accepts `admin`, `member` and `viewer`; the owner role is not assignable. |
| Admin | Admin, member and viewer. |

> **Note.** A member holds exactly one role on a product; to combine two sets of rights, define a role that carries both rather than assigning two roles. Nobody may lower their own role, and the owner's membership cannot be reassigned this way.

## Custom roles

Reusable custom roles are defined once on the organization and assigned many times. Products do not have their own role editor. They are managed with [`organization_roles_list`](/reference/mcp-tools/organization_roles_list), [`organization_roles_get`](/reference/mcp-tools/organization_roles_get), [`organization_roles_create`](/reference/mcp-tools/organization_roles_create), [`organization_roles_update`](/reference/mcp-tools/organization_roles_update) and [`organization_roles_delete`](/reference/mcp-tools/organization_roles_delete). Every member can read the list; only owners and admins can create, edit or delete. System roles are visible but read-only.

A role definition has a `name` and the two pattern lists, `allow` and `deny`. It is a template, not access in itself: access appears when you assign the definition on an invitation or a share, at which point its permissions are resolved and applied to that one product.

Two ways to describe the permissions on a grant:

| Way | When to use it |
| --- | --- |
| A role definition (`roleId`) | The same set of rights is handed out more than once. |
| An ad-hoc `permissions` object | A one-off set of rights on a single invitation or share. |

> **Note.** Permissions are copied at assignment time, so later edits to a definition do not rewrite access that was already granted. Two grants carrying the same set of permissions share one underlying role; identical grants are never duplicated.

## How a permission is evaluated

Every guarded operation has a stable permission key of the form `{area}_{entity}_{action}`, for example `organization_product_create`. For an MCP tool the key is the tool name.

A pattern matches keys segment by segment, splitting on `_`:

- `*` matches exactly one segment — `organization_*_list` matches `organization_member_list`;
- a trailing `*` matches one or more remaining segments — `organization_*` matches every key in the organization area;
- anything else must match the key exactly.

The decision is:

```text
allowed = matches any allow pattern AND matches no deny pattern
```

This is default-deny with a deny override. No matching `allow` pattern means the operation is refused, and a matching `deny` pattern always wins over an `allow`.

The check runs on every call before it reaches the service behind it.

## The permission catalog

The catalog is the browsable list of permission keys you pick from when you build a role or set ad-hoc permissions. It is derived from the platform's own operation handlers rather than maintained by hand, so it cannot drift. [`organization_permission_catalog`](/reference/mcp-tools/organization_permission_catalog) returns it as flat rows of `key`, `display_name`, `group`, `level` and `scope`.

`scope` decides whether a key can be granted at all: `product` entries are grantable in role and permission pickers, `user` entries are informational because they are about your own account rather than about one product.

The keys below are the ones covering organizations, membership, roles, products and domains. The catalog also contains keys for other areas of the platform, and it grows as the platform does — always read it from the tool rather than from this list.

| Key | Level | Scope |
| --- | --- | --- |
| `organization_auth_me` | read | user |
| `organization_create` | write | user |
| `organization_list` | read | user |
| `organization_select` | read | user |
| `organization_feedback_submit` | write | user |
| `organization_permission_catalog` | read | user |
| `organization_member_invite` | write | user |
| `organization_member_accept-invite` | write | user |
| `organization_member_list` | read | user |
| `organization_member_list-invitations` | read | user |
| `organization_member_revoke-invitation` | admin | user |
| `organization_member_list-product-access` | read | user |
| `organization_member_set-role` | admin | user |
| `organization_member_remove` | admin | user |
| `organization_member_share-product` | admin | user |
| `organization_member_unshare-product` | admin | user |
| `organization_members_assign-role` | admin | product |
| `organization_roles_list` | read | user |
| `organization_roles_get` | read | user |
| `organization_roles_create` | write | user |
| `organization_roles_update` | write | user |
| `organization_roles_delete` | admin | user |
| `organization_product_create` | write | user |
| `organization_product_list` | read | user |
| `organization_product_select` | read | user |
| `organization_product_update` | write | user |
| `organization_product_list-access` | read | product |
| `organization_product_set-access` | write | product |
| `organization_product_revoke-access` | write | product |
| `organization_product_list-members` | read | product |
| `organization_product_list-roles` | read | product |
| `organization_domains_add` | write | product |
| `organization_domains_get` | read | product |
| `organization_domains_list` | read | product |
| `organization_domains_remove` | admin | product |

## Next steps

- [Assign a role to a member](/access/organizations-and-members): the invite, share and set-role calls that put these roles to work.
- [Understand where a grant comes from](/access/product-access): why a role only ever applies through a concrete membership.
- [Browse the role endpoints](/reference/openapi/organization): every path, method and parameter behind the role tools.