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

# Permissions Model

> Access boundaries for primary managers, secondary managers, view-only users, registry maintainers, session keys, and keepers.

SuperVaults separates protocol ownership from day-to-day operations. The safest mental model is:

* **Primary manager** owns the vault.
* **Secondary managers** operate the vault.
* **View-only users** observe the vault.
* **Registry maintainers** maintain global metadata.
* **Session keys / keepers** execute narrowly-authorized automation.

## Role Tiers

| Role                 | Onchain?       | Scope                       | Typical Use                      |
| -------------------- | -------------- | --------------------------- | -------------------------------- |
| Primary Manager      | Yes            | Full vault control          | Multisig / hardware-backed owner |
| Secondary Manager    | Yes            | Operational controls        | PM, operations, risk             |
| View Only            | No             | Read access                 | Analysts, auditors, monitors     |
| Registry Maintainer  | No             | Global registry CRUD        | Internal registry operations     |
| Session Key / Keeper | Yes, delegated | Specific executable actions | Strategy and OMS automation      |

## Primary Manager

The primary manager is set at vault creation and is the highest-authority vault operator.

Primary manager responsibilities:

* Vault settings and sensitive configuration.
* Secondary-manager assignment.
* Session-key grant and revoke flows.
* Upkeep funding and withdrawal control.
* Pause, unpause, and emergency operations.
* Merkle root proposal / publish workflows.

<Warning>
  Treat the primary manager as production infrastructure. Use a multisig or hardware-backed wallet. If the primary manager key is compromised, the attacker can control the vault.
</Warning>

## Secondary Managers

Secondary managers are onchain delegates for operational work.

They can typically:

* Manage strategies.
* Configure yield sources.
* Work with merkle tree configuration.
* Pause/unpause operational services.
* Add view-only collaborators.

They cannot replace the primary manager or take over primary-only settings.

## View-Only Users

View-only access is offchain. It grants dashboard visibility without transaction authority.

Use it for:

* Risk monitors.
* Analysts.
* Auditors.
* Partners who need vault state without write access.

## Registry Maintainers

Registry maintainers manage global metadata shared across vaults, including:

* Yield source registry entries.
* Oracle registry entries.
* Hook registry entries.
* Token asset metadata.
* Admin backfills.

This role is not vault-scoped and should be tightly controlled.

## Session Keys and Keepers

Session keys are delegated execution keys used by automation. A session key does not imply broad manager authority; it authorizes a specific automation path.

Keepers and OMS execution still depend on:

* Active upkeep funding.
* Valid session key readiness.
* Active merkle root and proofs.
* Non-paused vault / services.
* Strategy state and emergency locks.

If any of those gates fail, automation should stop even when a session key exists.

## Permission Matrix

| Action                         | Primary | Secondary    | View Only | Registry Maintainer | Session Key / Keeper |
| ------------------------------ | ------- | ------------ | --------- | ------------------- | -------------------- |
| View dashboard                 | ✅       | ✅            | ✅         | —                   | —                    |
| Create vault                   | ✅       | —            | —         | ✅                   | —                    |
| Fund upkeep                    | ✅       | ✅            | ❌         | —                   | —                    |
| Withdraw upkeep                | ✅       | Usually ❌    | ❌         | —                   | —                    |
| Configure strategies           | ✅       | ✅            | ❌         | —                   | —                    |
| Reorder strategies             | ✅       | ✅            | ❌         | —                   | —                    |
| Manage yield sources           | ✅       | ✅            | ❌         | —                   | —                    |
| Configure hooks / merkle roots | ✅       | ✅            | ❌         | —                   | —                    |
| Propose or publish merkle root | ✅       | Permissioned | ❌         | —                   | —                    |
| Grant / revoke session key     | ✅       | Usually ❌    | ❌         | —                   | —                    |
| Pause vault                    | ✅       | ✅            | ❌         | —                   | —                    |
| Arm emergency exit             | ✅       | ✅            | ❌         | —                   | —                    |
| Add/remove secondary managers  | ✅       | ❌            | ❌         | —                   | —                    |
| Add/remove view-only users     | ✅       | ✅            | ❌         | —                   | —                    |
| Registry CRUD                  | —       | —            | —         | ✅                   | —                    |
| Execute authorized hooks       | —       | —            | —         | —                   | ✅                    |

## API Patterns

```bash theme={null}
# List vault users
GET /api/v1/users?vault_address={address}&chain_id={chainId}

# Prepare add secondary manager transaction
POST /api/v1/users/secondary-manager/prepare

# Prepare remove secondary manager transaction
POST /api/v1/users/secondary-manager/remove/prepare

# Add view-only user offchain
POST /api/v1/users/view-only

# Remove view-only user offchain
DELETE /api/v1/users/view-only/{wallet}
```

A `403 Forbidden` means the connected wallet lacks the required role for that operation.