---
title: "Configure roles and memberships"
source: "https://docs.vertesiahq.com/security/roles-memberships"
markdown: "https://docs.vertesiahq.com/llms/security/roles-memberships.md"
---

# Configure roles and memberships

Use role assignments for broad platform capabilities: who can administer a project, execute interactions, manage
content, run workflows, or use an application. Vertesia roles are built in; administrators assign them rather than
creating custom role definitions.

## Before you start

Organization owners and administrators can manage organization-wide users, groups, and access-control entries.
Project administrators can manage many project settings, but some organization-level identity and permission changes
still require an organization administrator.

Use least privilege: choose the smallest role that covers the required work, and review elevated `owner`, `admin`,
and `content_superadmin` assignments regularly.

## Assign a user to a project

1. Open **Project Settings**.
2. Select **Invitations**.
3. Invite the user and choose the project role appropriate for their work.
4. After the user accepts, verify the assignment under **Project Settings → Permissions**.

To change or remove an existing assignment, open **Project Settings → Permissions**, locate the user's entry, and use
its actions menu.

## Assign a role to a group

Group assignments keep access consistent as people join or leave a team.

1. Open **Organization Settings → Groups** and create or select a group.
2. Add the appropriate users to the group.
3. Open the target project's **Settings → Permissions** tab.
4. Select **New**.
5. Under **Who**, choose **User / Group / API Key**, then select the group.
6. Choose a system role.
7. Keep **Target Resource** set to **Project** and create the permission.

Users receive the union of roles granted directly and through their applicable groups.

## Assign an API-key role

Every API key has a base project role. Keep service keys narrowly scoped because the key acts independently of a
human user's current session.

1. Open **Project Settings → API Keys**.
2. Create a key and choose the smallest suitable base role.
3. Store the secret immediately in a secure secret manager; it is not intended for browser code.
4. If the key needs an additional project grant, add it from **Project Settings → Permissions**.

API keys can also carry ABAC attributes and participate in dynamic rules. See [Principal
attributes](/security/principal-attributes).

## Common system roles

| Role | Typical use |
| --- | --- |
| `owner` | Full organization and project control. Reserve for accountable organization owners. |
| `admin` | Full administrative access without changing the ownership model. |
| `manager` | Broad project operation with selected organization, billing, audit, and super-admin capabilities removed. |
| `developer` | Build and operate project resources without organization or project administration. |
| `reader` | Read interactions, runs, and content. |
| `executor` | Execute interactions and workflows with limited read access. |
| `automation` | Run automated content, interaction, and workflow operations. |
| `auditor` | Read-only access to operational, content, workflow, agent-run, billing, and audit information. |
| `member` | Organization membership without additional project capabilities. |
| `content_superadmin` | Full content visibility and mutation bypass. Assign only for trusted administration or processing. |

The complete role-to-permission mapping is available from the role catalog API. Developers can retrieve it with
`client.iam.roles.listSystem()`.

## Application access

Installed applications can have their own access policy. When an application requires explicit access, use its
**Manage Permissions** action to grant the appropriate users or groups. Application visibility does not automatically
grant the system permissions required by the APIs the application calls.

## Review assignments

Use both permission views during an audit:

- **Project Settings → Permissions** shows assignments and dynamic rules for the current project.
- **Organization Settings → Permissions** shows project-level entries across the organization.

Changes that affect token contents take effect when a new access token is issued. Refresh the session or recreate an
API-key token before testing a changed role.

## Next

- [Learn about Attribute-Based Access Control (ABAC)](/security/abac)
- [Configure principal attributes](/security/principal-attributes)
- [Build permission-aware applications](/security/developer-guide)