> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Access policies

> Define who can request access, approval requirements, and how long access lasts with access policies.

## Data model

`AccessPolicy` fields:

| Field                           | Type                          | Description                                                                                                                                                           |
| ------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                          | string                        | Display name                                                                                                                                                          |
| `description`                   | string                        | When this policy should be used                                                                                                                                       |
| `icon`                          | string                        | Lucide icon name                                                                                                                                                      |
| `color`                         | string                        | Hex color for visual identification                                                                                                                                   |
| `isDefault`                     | boolean                       | Marks the organization's default policy                                                                                                                               |
| `requiresBusinessJustification` | boolean                       | Whether requesters must provide a reason                                                                                                                              |
| `durationMode`                  | `choice` \| `fixed` \| `none` | Who controls the grant length. `choice` means the requester picks from `durationOptions`, `fixed` means `defaultDuration` is enforced, `none` means permanent access. |
| `durationOptions`               | string\[]                     | Durations offered when `durationMode` is `choice`. At least one is required in that mode.                                                                             |
| `defaultDuration`               | string \| null                | Required when `durationMode` is `fixed`. Also used to preselect an option in `choice` mode when it appears in `durationOptions`.                                      |
| `ownerId`                       | string                        | User responsible for managing the policy                                                                                                                              |
| `approvalTemplateId`            | string \| null                | When set, approval is required; when null, auto-approval                                                                                                              |

Relationships:

* `eligibleGroups` (`UserGroup[]`): groups allowed to request
* `ineligibleGroups` (`UserGroup[]`): groups explicitly excluded
* `accessLevels` (`AccessLevel[]`): levels this policy governs

***

## Policy evaluation flow

1. User submits an access request for an access level.
2. System looks up the access level's linked access policy.
3. Eligibility is checked: user must be in `eligibleGroups` (or no groups set) and must not be in `ineligibleGroups`. Deny wins over allow, so membership in an ineligible group excludes the user even when they are also in an eligible group.
4. If eligible: the approval template is applied (or the request is auto-approved if `approvalTemplateId` is null).
5. If ineligible: the request is blocked.

***

## Policy-driven form fields

The `DURATION` and `BUSINESS_JUSTIFICATION` fields on an access request form are gated by the selected access level's policy:

* The Duration field renders only for access levels whose policy uses `durationMode: choice` and has at least one entry in `durationOptions`. It is hidden for `fixed` and `none`.
* The Business Justification field renders only for access levels whose policy has `requiresBusinessJustification` set.
* When either field renders, it is required. Visibility implies requiredness, so the form's own required flag does not need to be set.

Both gates are honored in the web form and in Slack modals.

***

## Constraints

* Policies are organization-scoped.
* A policy can be linked to multiple access levels across different applications.
* `durationMode: fixed` requires a valid finite `defaultDuration`. Use `none` for permanent access rather than an unbounded fixed duration.
* A requested duration that is not one of the policy's `durationOptions` snaps to the closest allowed option rather than being accepted as-is. This matters for API and MCP submissions, where the duration is free-form. If no option can be resolved, the request is rejected.
* Switching duration modes preserves the inactive mode's configuration, so a stored `defaultDuration` may not be present in `durationOptions`.
* Removing a policy from an access level means that level falls back to auto-approval.
* The `isDefault` flag marks the organization's default policy, used when no specific policy is assigned to an access level.