---
title: "Configure principal attributes"
source: "https://docs.vertesiahq.com/security/principal-attributes"
markdown: "https://docs.vertesiahq.com/llms/security/principal-attributes.md"
---

# Configure principal attributes

Principal attributes are the input to Principal Set conditions and to `$principal.*` references in Resource Set
rules. Configure them before enabling a restrictive ABAC policy.

## Principal context

Vertesia evaluates dynamic rules against this logical context:

| Field | Meaning | User source | API-key source |
| --- | --- | --- | --- |
| `kind` | Authenticated principal type: `user` or `apikey` | Token subject | Token subject |
| `clearance` | Numeric security clearance | User and groups | API-key setting |
| `compartments` | Security domains such as `legal` or `finance` | User and groups | API-key setting |
| `email` | User email address | User profile | Empty string |
| `tags` | Group classification or organizational tags | Applicable groups | Empty list |
| `properties.*` | Custom organization-specific attributes | User and groups | API-key settings |

## How user and group attributes combine

For a user, Vertesia merges the user's attributes with attributes from groups that apply to the selected project:

- **Clearance** uses the highest configured value.
- **Compartments** are combined as a union.
- **Tags** are combined as a union.
- **Custom properties** are merged into the `properties` object.

Project-restricted groups contribute attributes only in projects they are allowed to cover. This prevents a group's
clearance or department properties from leaking into unrelated projects.

## Configure group attributes

Group attributes are the preferred way to manage shared organizational policy.

1. Open **Organization Settings → Groups**.
2. Create or edit a group.
3. Configure:
   - **Clearance** — a level from 0 (Public) through 4 (Secret).
   - **Compartments** — stable identifiers such as `legal`, `finance`, or `customer-a`.
   - **Tags** — labels that can select groups dynamically, such as `employee` or `finance`.
   - **Properties** — a JSON object containing fields such as `department`, `region`, or `employment_type`.
   - **Allowed Projects** — projects in which the group and its attributes apply.
4. Add the relevant users as members.
5. Save the group and issue a new user token before testing access.

Example custom properties:

```json
{
    "department": "legal",
    "region": "eu",
    "employment_type": "employee"
}
```

Conditions reference these values using paths such as `properties.department`.

## Configure user attributes

Organization administrators can edit a user's clearance, compartments, and custom properties from the organization
user-management view. Use direct user attributes for exceptions that should not be modeled as group membership.

Prefer group attributes for normal team policy. A large number of direct user exceptions is difficult to audit and
can produce surprising merged values.

## Configure API-key attributes

1. Open **Project Settings → API Keys**.
2. Locate the key and select **Edit properties**.
3. Set its clearance, compartments, and custom properties.
4. Save and issue a new token for the key before testing.

API keys do not inherit user or group attributes. Their principal context comes only from the key itself. Use a
Principal Set condition such as `kind = apikey` when a policy should apply only to service access.

### Delegate API-key attributes from automation

A project `admin` API key can manage security attributes on other API keys in the same project.

The admin key can create or update keys subject to these bounds:

- **Clearance** — when the admin key has a clearance, a target key's resulting clearance cannot exceed it. An admin key
  without a clearance may set any clearance.
- **Compartments** — when the admin key has compartments, the target key's resulting compartments must be the same
  unordered set. An admin key without compartments may set any compartments.
- **Properties** — custom properties are unrestricted.

Assign the `admin` role only to automation that must provision other project credentials.

## Naming guidance

- Keep compartment identifiers stable, lowercase, and machine-friendly.
- Use the same vocabulary on principals and resources.
- Store numerical policy fields such as security level in the dedicated clearance/sensitivity fields.
- Put organization-specific strings and booleans under `properties`.
- Avoid placing confidential values in authorization attributes; tokens may carry resolved policy information.

## Safe rollout checklist

Before enabling restrict mode:

1. Confirm every affected principal has the expected merged context.
2. Classify a small set of test documents or collections.
3. Create a narrow rule for a test group.
4. Refresh that user's token and verify both allowed and denied resources.
5. Add the global restrict-mode switch only after the granting rules are ready.

Continue with [Dynamic access rules](/security/dynamic-rules).