System Permissions

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.

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

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

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.

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

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 for details on how authorization works for contract calls and event queries.

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

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.

Rate Limit Bypass

Users with the following system permissions are exempt from API rate limiting:

• full_sequencer_rpc_access
• full_read_access
• contract_deployment
• admin_read

Granular RPC read permissions (rpc_read_*) do not bypass rate limiting.

This ensures that trusted users with elevated access can perform high-frequency operations without being throttled.

For rate limiting configuration and thresholds, see Rate Limiting.

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.