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

# Setting up access provisioning

> Step-by-step guide to configure applications, approval templates, access policies, access levels, and agent-assisted access requests.

Set up automated access provisioning so users can request application access through a form or your AI agent, each request routes to the right approvers, and access is granted automatically once approved. This guide walks through the complete setup from application catalog to agent-assisted requests.

<Callout icon="link" color="#6B7280">Learn about [access provisioning concepts](/documentation/automate/access-provisioning/overview)</Callout>

***

## How the pieces connect

Access provisioning is built from four layers that cascade into each other. You configure them from the bottom up:

| Layer                 | What it defines                                                                                                            | Attaches to               |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| **Approval template** | Who approves, in how many rounds, and whether any or all approvers must sign off                                           | An access policy          |
| **Access policy**     | Who is eligible to request, which approval template applies, allowed durations, whether business justification is required | One or more access levels |
| **Access level**      | A permission tier within an application, and how access is provisioned once approved                                       | An application            |
| **Application**       | The tool or service being requested                                                                                        | Your catalog              |

The result is a single access request form that adapts to each requester. Users pick an application and an access level, the form shows only what they are eligible for, the access policy routes the request to the approvers defined in its approval template, and provisioning runs through the access level's provisioning method.

<Note>You do not need to build a workflow for this. Approval routing and provisioning both happen automatically from the policy and access level configuration. Workflows are for the exceptions, covered in [optional workflow automation](#optional-workflow-automation) below.</Note>

***

## Before you begin

Before starting, make sure you have:

* An identity provider integration (Okta, Google Workspace, or Microsoft Entra ID) for automated provisioning
* An understanding of your organization's application catalog and which apps require access management
* A clear picture of who should approve access, so you can turn that into approval templates
* (Optional) An AI agent deployed to a Slack channel for conversational requests

***

## Step 1: Import or create applications

Applications are the foundation of access provisioning. You can sync them from your identity provider or create them manually.

<Steps>
  <Step title="Sync applications from your identity provider">
    Navigate to **Settings** > **Integrations**, connect your identity provider (Okta, Google Workspace, or Microsoft Entra ID), and enable application syncing. Applications and their groups import automatically.
  </Step>

  <Step title="Create applications manually">
    Navigate to **Settings** > **Applications**, click **Add Application**, and fill in the name, domain, owner, approver, and workspaces. Save the application when complete.
  </Step>
</Steps>

<Tip>Start with your most-requested applications. You can always add more later.</Tip>

<Callout icon="link" color="#6B7280">Learn about [applications and access levels](/documentation/automate/access-provisioning/applications)</Callout>

***

## Step 2: Create approval templates

Approval templates define who approves an access request and in what order. Create them first, because access policies reference them.

<Steps>
  <Step title="Navigate to approval templates">
    Go to **Settings** > **Approval Templates**.
  </Step>

  <Step title="Click New Template">
    Click **New Template** to open the template form.
  </Step>

  <Step title="Configure template details">
    Fill in the following fields:

    * **Name**: A descriptive label such as "Manager approval" or "Security access review"
    * **Description**: When this template should be used
    * **Workspaces**: Which workspaces can use this template. Leave empty to make it available everywhere.
  </Step>

  <Step title="Add approval rounds">
    Add one round per approval stage. For each round, set:

    * **Policy**: **Any can approve** or **All must approve**
    * **Approvers**: Specific users, user groups, or dynamic roles such as the requester's manager
  </Step>

  <Step title="Save the template">
    Save the template. It is now available to attach to an access policy.
  </Step>
</Steps>

Create one template per approval path you need. A typical setup looks like this:

| Template               | Rounds                                                          | Use for                           |
| ---------------------- | --------------------------------------------------------------- | --------------------------------- |
| Manager approval       | Manager review (any can approve)                                | Standard, low-risk access         |
| Team lead and IT       | Manager review, then IT sign-off                                | Access managed by a specific team |
| Security access review | Manager review, security review (all must approve), IT sign-off | Admin and privileged access       |

<Tip>Use the **Requester's manager** dynamic approver rather than naming individuals. It resolves at request time, so the template keeps working as your org chart changes.</Tip>

<Callout icon="link" color="#6B7280">Learn about [approval templates](/documentation/tickets/approvals/templates)</Callout>

***

## Step 3: Create access policies

Access policies define who can request access and under what conditions. Each policy attaches one approval template, which is how requests get routed.

<Steps>
  <Step title="Navigate to the Policies tab">
    Go to **Settings** > **Applications** and open the **Policies** tab.
  </Step>

  <Step title="Click New Policy">
    Click **New Policy** to create a new policy.
  </Step>

  <Step title="Configure policy details">
    Fill in the following fields:

    * **Name**: A descriptive label such as "Standard access" or "Privileged access review"
    * **Description**: When this policy should be used
    * **Eligible groups**: Which user groups can request access under this policy. Leave empty to allow all users.
    * **Ineligible groups**: Which user groups are explicitly excluded
    * **Approval template**: The template you created in Step 2. Leave blank only if requests under this policy should be approved automatically.
    * **Access Duration**: How long access granted under this policy lasts. See the table below.
    * **Business Justification**: Toggle on if requesters must explain why they need access
  </Step>

  <Step title="Save the policy">
    Save the policy. You attach it to access levels in the next step.
  </Step>
</Steps>

### Choosing an access duration

| Mode                           | What happens                                                                 | Also configure                                                          |
| ------------------------------ | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| **Requester picks a duration** | The requester chooses from a list of allowed durations on the request form   | **Duration Options**: the durations to offer, such as `10m`, `1h`, `1d` |
| **Fixed duration**             | Access always lasts a set amount of time, with no duration field on the form | **Duration**: the enforced length, such as `8h`                         |
| **No expiry**                  | Access is permanent, with no duration field on the form                      | Nothing                                                                 |

Durations use short-form notation: `m` for minutes, `h` for hours, `d` for days.

<Note>A policy with no approval template auto-approves every request that passes its eligibility check. Attach a template to any policy that needs a human decision.</Note>

Create a policy for each combination of eligibility and approval rigor you need. Because a single policy can be shared across access levels in different applications, a handful of policies usually covers an entire catalog.

<Callout icon="link" color="#6B7280">Learn about [access policies](/documentation/automate/access-provisioning/policies)</Callout>

***

## Step 4: Define access levels

Access levels represent the permission tiers within each application, such as Admin, Editor, or Viewer. Each level attaches an access policy and specifies how access is provisioned.

<Steps>
  <Step title="Open an application">
    Navigate to **Settings** > **Applications** and open the application you want to configure.
  </Step>

  <Step title="Go to the Access Levels tab">
    Select the **Access Levels** tab on the application detail page.
  </Step>

  <Step title="Click Add Access Level">
    Click **Add Access Level** to begin configuring a new tier.
  </Step>

  <Step title="Name and describe the level">
    Set the **Name** to a descriptive label such as "Admin", "Editor", or "Viewer", and use **Description** to explain what this level grants and when it should be requested.
  </Step>

  <Step title="Attach an access policy">
    Select the **Access Policy** that should govern this level. This is what determines eligibility and pulls in the approval template you configured in Step 2.
  </Step>

  <Step title="Choose the provisioning method">
    Set **Provisioning Method** to control how access is granted after approval. See the table below for which to pick.
  </Step>

  <Step title="Map to your identity provider group">
    For Group provisioning, select the corresponding group in your identity provider. This is how Ravenna knows which group to add the user to after approval.
  </Step>

  <Step title="Repeat for each permission tier">
    Add an access level for every permission tier your application supports. Levels with different approval requirements should point at different access policies.
  </Step>
</Steps>

### Choosing a provisioning method

| Method          | How access is granted                                                                     | When to use it                                                                                                          |
| --------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Group**       | Ravenna adds the user to the mapped identity provider group                               | Your default for synced applications. Supported on Okta, Google Workspace, and Microsoft Entra ID.                      |
| **Application** | Ravenna assigns the user directly to the application in the identity provider             | Okta applications where direct assignment is preferred over groups                                                      |
| **Manual**      | An authorized provisioner grants access in the target system, then confirms it in Ravenna | Tools with no identity provider connection                                                                              |
| **Workflow**    | Ravenna hands the approved request off to a workflow you build                            | Complex provisioning that the other methods cannot express, such as calling an external API or chaining several systems |

Group and Application are the methods that give you end-to-end automation. Reach for Workflow only when the provisioning itself needs custom logic.

***

## Step 5: Configure the request form

The form is how users submit access requests, and it is also what your AI agent presents. Create one form for access requests and let the field configuration adapt it per requester.

<Steps>
  <Step title="Create or open a form">
    Go to **Forms** and create a new form (or edit an existing one).
  </Step>

  <Step title="Add an Application Select field">
    Add an **Application Select** field. This lets users choose from the applications in your catalog.
  </Step>

  <Step title="Add an Access Level Select field">
    Add an **Access Level Select** field. This field dynamically shows the access levels available for the selected application, filtered by the requester's eligibility.
  </Step>

  <Step title="Add a Business Justification field">
    Add a **Business Justification** text area field. It renders only for access levels whose policy requires a justification, and it is required whenever it renders.
  </Step>

  <Step title="Add a Duration field">
    Add a **Duration** field. It renders only for access levels whose policy uses **Requester picks a duration**, and it is required whenever it renders. Levels on a fixed duration or no expiry hide it automatically.
  </Step>

  <Step title="Save and publish the form">
    Save your form and publish it so it is available to users.
  </Step>
</Steps>

<Note>The Access Level Select field is dependent on the Application Select field. It only shows access levels for the selected application, filtered by the requester's eligibility based on the attached access policy.</Note>

<Tip>Add both the Business Justification and Duration fields even if only some policies need them. The access policy decides whether each one appears, so you do not need a separate form per policy.</Tip>

One form covers your whole catalog. Because eligibility filtering and policy-driven fields both resolve per requester, two people opening the same form see different applications, different access levels, and different fields.

***

## Step 6: Enable agent-assisted requests

Once your form is published, you can enable your AI agent to handle access requests conversationally through Slack. The agent fills out and submits the form you built in Step 5, so it inherits the same eligibility filtering, approval routing, and provisioning.

<Steps>
  <Step title="Open your agent">
    Navigate to **Agents** in the sidebar and select the agent you want to configure.
  </Step>

  <Step title="Go to the Identity tab">
    Select the **Identity** tab on the agent configuration page.
  </Step>

  <Step title="Enable Software Access Requests">
    Scroll to the **Advanced Settings** card and toggle **Software Access Requests** on. This exposes eligibility-aware tools to the agent.
  </Step>

  <Step title="Create agent rules for access request scenarios">
    Add rules to guide the agent's behavior, for example: "When a user asks for software access, present the Software Access Request form and prefill the application and access level from what they described."
  </Step>

  <Step title="Deploy the agent to your Slack channel">
    Deploy the agent to your Slack channel so users can submit access requests conversationally.
  </Step>
</Steps>

<Warning>The agent needs a published access request form to work with. It does not have a built-in form of its own, so complete Step 5 before enabling this.</Warning>

<Note>Requests submitted through the Ravenna API or an MCP client are different. They do not need a form you built, because Ravenna creates and reuses a **Software Access Request** form in the target workspace. It appears in **Forms** with a **System** badge and is marked **Managed by Ravenna**, so it cannot be edited. Leave it in place.</Note>

<Callout icon="link" color="#6B7280">Learn about [software access requests for agents](/documentation/automate/access-provisioning/agent)</Callout>

***

## Step 7: Test the flow

Validate the complete setup before rolling it out to your organization.

<Steps>
  <Step title="Submit a test request">
    Submit a test access request via the form or through the agent.
  </Step>

  <Step title="Verify approval routing">
    Confirm that the access policy's approval template was applied to the ticket and that the expected approvers were notified.
  </Step>

  <Step title="Approve and verify provisioning">
    Approve the request and confirm that provisioning occurs. For synced applications, check the identity provider to verify the user was added to the correct group.
  </Step>

  <Step title="Confirm the entitlement is created">
    Verify that the entitlement appears in the **Entitlements** tab on the relevant application.
  </Step>

  <Step title="Test manual provisioning">
    For access levels using Manual provisioning, test the flow by marking the entitlement as provisioned after granting access in the target system.
  </Step>
</Steps>

<Tip>Test with a real requester from an eligible group, not just an admin account. Eligibility filtering is the part most likely to surprise you.</Tip>

***

## Optional workflow automation

Your access provisioning setup is complete without any workflows. Add one only when you need behavior the policy and access level configuration cannot express:

* **Custom provisioning logic**: set an access level's provisioning method to **Workflow** and build a workflow that performs the provisioning steps, such as calling an external API or chaining several systems together.
* **Post-provisioning follow-up**: use the **Entitlement Status Changed** trigger to send a confirmation message, alert on provisioning failures, or notify a team when access is revoked.

<Callout icon="link" color="#6B7280">Learn about [workflow triggers and actions](/documentation/automate/workflows/triggers-actions)</Callout>

***

## Next steps

<CardGroup cols={2}>
  <Card title="Monitor entitlements" icon="key" href="/documentation/automate/access-provisioning/entitlements">
    Track active access grants and handle provisioning failures.
  </Card>

  <Card title="Refine policies" icon="shield-check" href="/documentation/automate/access-provisioning/policies">
    Adjust eligibility and duration options based on usage patterns.
  </Card>

  <Card title="Add more applications" icon="grid-2" href="/documentation/automate/access-provisioning/applications">
    Expand your catalog as teams request additional tools.
  </Card>

  <Card title="Tune approval templates" icon="user-check" href="/documentation/tickets/approvals/templates">
    Add rounds or dynamic approvers as your approval requirements evolve.
  </Card>
</CardGroup>