---
title: "Security & Access Control"
source: "https://docs.vertesiahq.com/security/overview"
markdown: "https://docs.vertesiahq.com/llms/security/overview.md"
---

# 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](/security/abac).

## 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.

  Roles apply at the level where you grant them. A role granted on the **organization** (account) applies
  across every project; a role granted on a single **project** applies only there.

## 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.

### Advanced: how a permission check resolves

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.

  If nothing anywhere restricts a given permission, the document stays open to the project. Restriction is
  always something you add deliberately; the safe default is never to silently lock content away.

### Advanced: the cascade in detail

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](/security/abac).

## Configure access control

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