Security & Access Control

Access in Vertesia is decided by roles. You grant a person (or a group, or an API key) a role on a project or on your whole organization, and that role decides what they can do — read content, run interactions, build workflows, manage settings, and so on.

This page covers the standard model an administrator uses day to day: roles, how you grant them, and how access to content flows from collections down to the documents inside them. For rules based on attributes — clearance levels, departments, document sensitivity — see Attribute-Based Access Control.

Roles

A role is a named bundle of permissions. You never assign individual permissions by hand; you pick a role, and the role carries the right set. The most common roles an administrator assigns:

Role	What it grants
Owner	Full control, including account settings and billing.
Admin	Full control of the project or organization.
Manager	Manage everything except account settings and billing.
Developer	Build and manage interactions, content, and workflows. No account, billing, or role administration.
Executor	Read and run interactions only.
Reader	Read-only access — browse content and configuration, change nothing.
Consumer	For end users of a micro-application built on Vertesia.
Member	Baseline membership. Marks that someone belongs to the project; grants no specific actions on its own.
Billing	Manage billing only.
Auditor	Read everything except administration, with no ability to make changes.

A few additional roles exist for machine identities and system tasks — application and automation (for apps and event-triggered runs), content_processor (trusted content processing), and content_superadmin (see all content in a project). You rarely assign these by hand.

Granting access

Access is stored as Access Control Entries (ACEs). Each entry is simply: this principal has this role on this resource.

• Principal — a user, a group, or an API key.
• Resource — a project, the organization, an environment, or an interaction.
• Role — one of the roles above.

In Studio, go to the Settings. From there you can add a user or group to a project and choose their role, manage groups, and review or revoke existing grants.

Groups make this easier at scale: grant a role to a group once, and every member of that group receives it. A person's effective permissions are the combination of every role they hold — directly and through their groups.

When someone makes a request, the platform collects all the roles they hold (from direct grants and group memberships, at both the account and project level), unions the permission sets of those roles, and checks the required permission against that union. Permissions are always computed fresh from the roles — there is no separate stored permission list to keep in sync. Endpoints declare the permission they require (for example content:read, interaction:execute, project:admin), and the request is allowed only if one of the caller's roles includes it.

Content visibility: projects, collections, and documents

Content permissions (content:read, content:write, content:delete) come from the roles above, but there is a second question: which documents does a grant apply to?

By default, a project's content is open to its members. Every document and every collection is created "open to the project" — anyone whose role includes content read can see all of the project's content, and anyone whose role includes content write or delete can change it. Collections at this stage are for organizing content and for propagating shared metadata; they do not, by themselves, narrow who can see a document.

You restrict content by naming specific users, groups, or roles on a collection or document instead of leaving it open to the whole project. The moment you do, that item becomes restricted — only the named principals keep access. And because documents belong to collections, a restriction placed on a collection flows down to the documents inside it.

How access flows from collections to documents

When a document belongs to one or more collections, its effective access is worked out from those collections, one permission at a time (read, write, and delete are resolved independently):

• Open means open to everyone in the project. As long as an item is left open, project members with the matching content permission can access it.
• A specific grant restricts. Naming specific users, groups, or roles turns "open to the project" into "only these principals." Restriction anywhere wins over "open" — you cannot accidentally re-open a restricted document by also leaving it open somewhere else.
• The closest collection wins. A document takes its access from the nearest collection that says something specific about that permission. A rule on the collection the document sits in directly overrides a rule on a parent collection above it.
• Siblings combine. If a document belongs to several collections at the same level that each name specific principals, those principals are added together.

The engine groups a document's collections by distance — distance 0 is a collection the document is a direct member of, distance 1 is a parent, distance 2 a grandparent, and so on. For each permission it starts at distance 0, drops any "open to the project" entries, and unions the remaining specific principals. If that distance produced any specific principals, they win and the search stops for that permission; if it produced none, the engine moves out to the next distance. If no distance anywhere names a specific principal, the permission falls back to "open to the project." This is why the closest collection wins, siblings at the same distance combine, and a single restriction anywhere is enough to lock a document down.

How the access layers combine

Vertesia evaluates content access in three layers:

1. RBAC permission — the principal needs a system role that permits the requested operation.
2. Direct resource grants — a document or collection can name users or groups for read, write, and delete.
3. ABAC rules — a Principal Set and Resource Set can grant a content role when their attributes match.

If a principal has an ABAC condition for an operation and scope, that operation enters restrict mode for that principal and scope. The usual project:* grant no longer provides blanket access. A document or collection is available when it directly names the principal or one of their groups, or when at least one matching ABAC rule grants the operation. Direct grants and ABAC rules are additive; there is no deny rule that overrides another grant.

Document and collection scopes are independent. A document rule does not restrict collection listings, and a collection rule does not restrict the documents inside it. Configure both scopes when the policy must protect both.

For attribute-based policies such as department isolation or clearance versus sensitivity, continue to Attribute-Based Access Control.

Configure access control

• Roles and memberships — assign built-in roles to users, groups, and API keys.
• Principal attributes — configure the values used by Principal Sets.
• Dynamic access rules — create and test document and collection ABAC rules.
• Content security — classify resources and manage direct grants.
• Developer guide — build applications that respect Vertesia authorization.