> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://docs.prividium.com/api/mcp` to find what you need.
>
> **Have feedback?** Use `submit_feedback` on the same MCP server.

System permissions are **special access grants** (the RBAC layer) that bypass the normal contract-level authorization
checks. They provide elevated access to the blockchain and should be assigned carefully to trusted users only.

## Overview

Unlike contract permissions (which control access to specific smart contract functions), system permissions grant
broader access that operates at the RPC level. When a user has a system permission, certain permission checks are
skipped entirely, allowing direct interaction with the sequencer or full read access to chain data.

:::info
System permissions are powerful capabilities. Assign them only to users who genuinely need this level of access.
:::

## Available System Permissions

### Contract Deployment

**Permission key:** `contract_deployment`

Allows users to deploy smart contracts to the chain using common deployment tools. Users with this permission can:

* Deploy contracts using ethers.js, viem, Hardhat, or Foundry
* Continue to be subject to normal contract-level permission checks for all other operations

:::tip
For Foundry script deployments, ensure the `EXTRA_PUBLIC_CODE_ADDRESSES` environment variable includes your network's
fee collector address.
:::

### Full Sequencer RPC Access

**Permission key:** `full_sequencer_rpc_access`

Bypasses **all** permission checks and forwards requests directly to the sequencer RPC. Users with this permission can:

* Interact with any smart contract without restriction
* Access all on-chain data
* Use any wallet address
* Deploy smart contracts

:::note
Requests still go through the Prividium™ API and require authentication. Once verified, no further contract-level
permission checks are performed.
:::

### Full Read Access

**Permission key:** `full_read_access`

Grants access to read the entire chain. Users with this permission can:

* Access every block
* Read every transaction
* View every receipt
* Query all event logs

### Granular RPC Read Permissions

For cases where `full_read_access` is too broad, Prividium™ offers per-method system permissions that grant
unrestricted access to a single filtered RPC method.

| Permission key                       | Grants unrestricted access to |
| ------------------------------------ | ----------------------------- |
| `rpc_read_eth_getBlockByNumber`      | `eth_getBlockByNumber`        |
| `rpc_read_eth_getLogs`               | `eth_getLogs`                 |
| `rpc_read_eth_getTransactionByHash`  | `eth_getTransactionByHash`    |
| `rpc_read_eth_getTransactionReceipt` | `eth_getTransactionReceipt`   |

:::tip
Prefer granular RPC read permissions over `full_read_access` when a role only needs visibility into specific data. For
example, a monitoring service that only queries logs can be granted `rpc_read_eth_getLogs` without exposing blocks or
transactions.
:::

On an organization-scoped role, a granular permission is confined to that organization's contracts and members, and it
stays method-specific. `rpc_read_eth_getLogs` on an organization role reveals every log the organization's contracts
emit, through `eth_getLogs` only. It does not make the transactions behind those logs visible: `eth_getTransactionReceipt`,
`eth_getTransactionByHash` and the block methods keep applying the normal rules unless the role also holds the matching
permission.

### Admin Read Access

**Permission key:** `admin_read`

Grants read-only access to the admin panel. Users with this permission can view all configuration (roles, users,
contracts, permissions) through admin API GET routes but cannot create, update, or delete resources.

This permission enables auditor or viewer personas who need visibility into system configuration without the risk of
accidental mutations.

In the Admin Dashboard, read-only admins see all data but write controls are hidden or disabled:

* Create, edit, and delete buttons do not appear
* Navigation to create forms redirects to the dashboard with a notification
* Form fields display as disabled

:::note
Write operations (POST, PUT, DELETE) on admin routes require the separate `admin_write` permission described below.
:::

### Admin Write Access

**Permission key:** `admin_write`

Grants write access to the admin panel: create, update, and delete resources (roles, users, contracts, permissions)
through admin API POST, PUT, and DELETE routes. Pair it with `admin_read` to give a role full read-write admin access.

Because of its blast radius, `admin_write` is treated as a high-privilege permission: holders must complete multi-factor
authentication (MFA) at login before a session is issued.

### M2M Organization User Management

**Permission key:** `org_users_manage`

Allows M2M applications to create and list users within their linked organizations. Users created through the M2M app
are automatically assigned the organization's default roles.

### M2M Organization Wallet Management

**Permission key:** `org_wallets_manage`

Allows M2M applications to attach wallet addresses to users in their linked organizations. Wallet addresses must be
fresh EOAs (not already registered, nonce 0, not a smart contract).

Creating a user with wallet addresses requires both `org_users_manage` and `org_wallets_manage`.

### M2M Organization RPC Access

**Permission key:** `org_rpc_access`

Allows M2M applications to make RPC calls on behalf of users in their linked organizations. See
[M2M Applications](/configuring/applications/m2m-applications) for details on how authorization works for contract calls
and event queries.

### M2M Organization Policy Access

**Permission key:** `org_policy_access`

Allows M2M applications to use the governance policy engine on behalf of their linked organizations: request a decision
for an operation, read the approval queue, vote where a rule permits machine approvers, and cancel their own requests.

Grant this only to integrations that actually submit operations. Without it, an M2M application linked to an
organization for another purpose — RPC reads, for example — cannot read pending operations or consume the organization's
cumulative spending allowance.

Cancelling is additionally restricted to the identity that raised the request, or an organization admin, so one
integration cannot withdraw another's pending approval.

The role editor offers this permission only while the policy engine is enabled. A role that already holds it keeps it
when the engine is disabled: the editor marks it "Feature not enabled" and lets you remove it, and it grants nothing
until the engine is enabled again.

### Organization Asset Instruction Permissions

**Permission keys:** `org_asset_instructions_submit`, `org_asset_instructions_read`, `org_asset_instructions_correct`

These three organization-scoped permissions gate [asset instructions](/developers/asset-instructions/overview), which
turn source-system events into sequenced, policy-governed token operations. The role editor offers them only while that
feature is configured. A role that already holds one keeps it when the feature is removed: the editor marks it "Feature
not enabled" and lets you remove it, and it grants nothing until the feature is configured again.

* `org_asset_instructions_submit` lets an M2M application submit instructions for the source systems it is bound to.
  Submission grants no read access.
* `org_asset_instructions_read` lets a user or M2M application read the organization's instruction records and queue
  diagnostics.
* `org_asset_instructions_correct` lets a user or M2M application request a corrective mint or burn for the source
  systems it is bound to. The deployment's separate correction signer executes it only after an independent human
  approval under the organization's policy.

### M2M Check User Read Access

**Permission key:** `check_user_read_access`

Allows an M2M application to query whether a given user has `full_read_access` via the
`POST /m2m-app-queries/check-user-read-access` endpoint. Used by webhook services and indexers that gate per-user data
delivery.

### M2M Contract Metadata Read

**Permission key:** `contract_metadata_read`

Allows an M2M application to read contract metadata (address, ABI, template) for any registered contract via
`GET /m2m-app-queries/contracts/:contractAddress`. Used by webhook services and indexers that need contract info without
broader RPC access.

## How System Permissions Work

System permissions are assigned to **roles**, not directly to users. When a user is assigned a role that has system
permissions, they inherit those capabilities.

```
User → Role → System Permissions
```

The permission check flow:

1. User makes an RPC request
2. Prividium™ API authenticates the user
3. System checks if user's roles include the required system permission
4. If **Full Sequencer RPC Access**: Skip all permission checks, forward to sequencer
5. If **Contract Deployment** and request is a deployment: Allow the deployment
6. If **Full Read Access**: Allow read operations for any on-chain data
7. If **Granular RPC Read** permission matches the requested method: Allow unrestricted access for that method
8. If **Admin Read Access** and request is a GET on an admin route: Allow read-only admin access
9. If **Admin Write Access** and request is a write (POST, PUT, DELETE) on an admin route: Allow the mutation
10. Otherwise: Apply normal contract permission rules

## What an Organization Admin Can Grant

An organization admin is bounded to the organization-scoped permissions — `org_users_manage`, `org_wallets_manage`,
`org_rpc_access`, `org_policy_access` and the three `org_asset_instructions_*` permissions. They cannot put any other
system permission on a role they create, and they cannot assign an existing organization role that carries one, so a
zone permission such as `contract_deployment` never reaches a member through an organization admin. A zone operator
(`admin_write` on the whole zone) is not bounded and can still make that assignment. The organization's own Admin role
is exempt from the check, since delegating it grants nothing the organization admin does not already hold.

## The Admin Role

The built-in `admin` role automatically has **all system permissions** enabled:

* Contract Deployment
* Full Sequencer RPC Access
* Full Read Access
* Admin Read Access
* Admin Write Access

This ensures administrators have unrestricted access to manage and interact with the chain.

## RPC Safety Caps

RPC batch and concurrency caps apply to every caller, including users with elevated permissions and legacy tenants or
services. These caps remain active when request quotas are disabled.
See [RPC Batch and Concurrency Caps](/configuring/applications/rate-limiting#rpc-batch-and-concurrency-caps).

## Rate Limit Bypass

Users with the following system permissions on a zone-scoped role bypass authenticated per-window request quotas:

* `full_sequencer_rpc_access`
* `full_read_access`
* `contract_deployment`
* `admin_read`

Organization-scoped roles and granular RPC read permissions (`rpc_read_*`) do **not** grant this bypass.

These permissions bypass authenticated per-window request quotas. Other limits still apply.

:::note
Legacy tenants and services, when enabled, also bypass authenticated per-window request quotas.
:::

For rate limiting configuration and thresholds, see [Rate Limiting](/configuring/applications/rate-limiting).

## Limits Before Authentication

All callers remain subject to `RATE_LIMIT_IP_MAX` before authentication on RPC, authenticated organization routes,
M2M query routes, and enabled legacy tenant routes. Clients sharing one outbound IP share this allowance, including privileged users and legacy services.
See [Limits Before Authentication](/configuring/applications/rate-limiting#limits-before-authentication) for configuration.

## Best Practices

* **Principle of least privilege**: Only grant system permissions when contract-level permissions are insufficient.
* **Use granular RPC read permissions when possible**: Prefer `rpc_read_*` permissions over `full_read_access` when a
  role only needs specific methods. This limits exposure while still bypassing address-based filtering.
* **Prefer Full Read Access for read-only services**: Use this instead of Full Sequencer RPC Access for indexers and
  analytics that need access to all read methods.
* **Audit periodically**: Review which roles have system permissions and whether they're still necessary.