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

# Roles and permissions

> Give people the minimum Forge feature, system, and tool access required for their work.

Forge roles are scoped to the organization. A role combines product feature permissions with system and tool access; some workflows add their own permission levels.

## Permission layers

### Feature access

Features commonly use levels such as **None**, **Read**, and **Write**. A user who can read a page may still be unable to create, edit, approve, or administer its records.

### System access

System access determines whether the role can use a connected system at all.

### Tool access

Within an allowed system, tools can be classified by effect, such as read, protected read, or write. Grant only the tools needed for the role's actual workflows.

### Workflow-specific access

Custom Agent access can distinguish reading, dry running, and writing. Other surfaces can include specific review, administration, or execution permissions.

## Design a role

<Steps>
  <Step title="Start from a job">
    List the Forge pages, records, and external actions a helpdesk engineer, project manager, reviewer, or administrator actually needs.
  </Step>

  <Step title="Grant feature access">
    Keep unrelated sections at None. Separate review from configuration or execution where the product permits it.
  </Step>

  <Step title="Grant systems and tools">
    Add the smallest usable set. Treat external communication and administrative writes as distinct risks.
  </Step>

  <Step title="Test the role">
    Assign it to a pilot user and check navigation, Chat tools, protected reads, writes, Custom Agent dry runs, and denied actions.
  </Step>

  <Step title="Review after rollout">
    Use the Audit Log, run outcomes, and support requests to remove unused access or add a justified capability.
  </Step>
</Steps>

## Clone with care

Cloning a role can copy feature permissions, system access, tool access, and workflow eligibility. Treat the clone as a starting point and review every layer before assigning users.

## Common problems

| Symptom                                   | Check                                                                    |
| ----------------------------------------- | ------------------------------------------------------------------------ |
| A section is missing                      | Feature permission and feature rollout.                                  |
| A connected system is absent from Chat    | System access, context, connection state, and surface Availability.      |
| A tool is visible but cannot run          | Tool permission, mode, approval, target mapping, or provider capability. |
| A user can only dry run an agent          | Custom Agent permission level.                                           |
| An admin test works but a user test fails | Effective role and organization scope.                                   |

<Tip>
  Test permissions from the user's role. Administrator access can hide gaps that will appear in daily work.
</Tip>