Access control for developers

Vertesia APIs enforce roles, permissions, direct resource grants, and dynamic content rules. Applications should use those APIs as the authorization boundary and use client-side checks only to improve the user experience.

Do not duplicate authorization in the browser

Client-side permission checks are useful for hiding unavailable actions or routes, but they are not a security boundary. A user can modify browser code or call an API directly.

Use this pattern:

1. Let Vertesia APIs enforce every protected read and mutation.
2. Use the current principal's system permissions to adapt the interface.
3. Treat a 403 or 404 from the API as authoritative.
4. Never fetch a broad dataset and filter sensitive records only in the browser.

ABAC conditions are already resolved and enforced by content APIs. Applications normally should not decode and reimplement the condition language.

Retrieve the role catalog

The client exposes both the complete role catalog and the system-role subset:

const roles = await client.iam.roles.list();
const systemRoles = await client.iam.roles.listSystem();

Use listSystem() when building permission-aware controls because its permissions use the platform permission vocabulary. The complete catalog also includes content roles used by dynamic Resource Set rules.

Role definitions are built in and can change as Vertesia adds capabilities. Retrieve the catalog instead of copying a role-to-permission table into application code.

Inspect project access-control entries

Administrative applications can list entries for the active project:

const entries = await client.iam.aces.listProjectAces();

An entry identifies its principal, principal type, role, target resource, resource type, and optional dynamic conditions. Treat these entries as administrative policy data. Do not expose them to users who lack permission to inspect account access.

Creating, updating, and deleting entries requires elevated IAM permissions. Prefer the Studio configuration pages for human administration unless the application is explicitly an access-management application.

Work with content APIs

Content reads, searches, counts, and facets automatically apply the current token's visibility policy. A list result contains only resources the principal may read.

For mutations:

• a system role must grant the operation, such as content:write;
• the resource must also pass its direct or dynamic content policy;
• a collection may propagate its security and classification to member objects.

Do not assume that being able to read a document implies permission to update or delete it. Dynamic roles may grant different operation sets.

Token lifecycle

Roles, group memberships, principal attributes, and dynamic rules are resolved when a token is issued. After an administrator changes policy, obtain a new token before testing.

For user sessions, refresh or restart the authenticated session. For API keys, issue a new access token using the updated key context.

Long-running agents inherit the effective user's content conditions when their agent token is created. Start a fresh run when validating changed access policy.

Error handling

Handle authorization outcomes without leaking resource details:

• 401 Unauthorized — the token is missing, invalid, or expired. Reauthenticate.
• 403 Forbidden — the principal is authenticated but cannot perform the mutation or administrative action.
• 404 Not Found — the resource may not exist or may be hidden by its read policy. Do not reveal which case applies.

Search and list APIs usually omit inaccessible records rather than returning one error per hidden record.

Test matrix

Before releasing a permission-aware application, test:

Related guides

• Access control overview
• Configure roles and memberships
• Configure dynamic access rules
• Configure content security