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
- Open Project Settings.
- Select Invitations.
- Invite the user and choose the project role appropriate for their work.
- 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.
- Open Organization Settings → Groups and create or select a group.
- Add the appropriate users to the group.
- Open the target project's Settings → Permissions tab.
- Select New.
- Under Who, choose User / Group / API Key, then select the group.
- Choose a system role.
- 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.
- Open Project Settings → API Keys.
- Create a key and choose the smallest suitable base role.
- Store the secret immediately in a secure secret manager; it is not intended for browser code.
- 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.
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.