> **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. Prividium combines identity, wallet ownership, role-based access control, and contract permissions to create controlled access flows on every request. Use this page as a guided FAQ before configuring zones, organizations, users, roles, wallets, or applications. ## What Is the Access Model at a High Level? Before someone can view data, call a contract, deploy a contract, or manage settings, Prividium checks who they are, which wallet or application they use, which roles they have, and whether the action belongs to the zone or one organization. ### Concepts | Concept | What it means | | -------------------- | ------------------------------------------------------------------------------------------------------------------- | | Zone | The whole Prividium deployment | | Organization | A user group with shared settings and scoped resources | | Wallet | An onchain address a user has proven they control - a wallet does not grant access by itself | | Contract Permissions | Granular function-level permissions that determine who can read or write to a smart contract | | System Permissions | Permissions that grant access to systems outside of smart contracts, or that bypass contract-level permissions | | Role | A named set of system permissions and contract permissions that can be assigned to different users and applications | | User application | A frontend that lets users sign in with Prividium | | M2M application | A machine principal that authenticates with API keys | ### User Types | User Type | Description | | ------------------- | ----------------------------------------------------------------------- | | Zone operator | A registered user who can manage the whole zone | | Organization admin | A registered user who can manage one organization | | User | A registered identity that signs in through OIDC, wallet login, or both | | Unregistered person | Someone who has no Prividium user record yet | An unregistered person is not a user in the Prividium access model. They do not have roles, linked wallets, organization membership, Admin Panel access, User Panel access, ordinary Explorer access, or authenticated RPC access. They can only use intentionally public surfaces, such as public RPC methods (`eth_chainId`, `eth_blockNumber`) and selective-disclosure methods when those features are enabled. How someone becomes registered depends on the sign-in method. An admin can also create a user before they sign in, and the first sign-in then uses that record. Wallet login depends on `AUTH_METHODS`. When it includes `crypto_native`, wallet login only works for a wallet that is already linked to a user, except for wallets listed in `CRYPTO_NATIVE_ADMIN_WALLETS`, which Prividium registers as zone admins the first time they request a sign-in challenge. When `AUTH_METHODS=oidc`, wallet login registers no one. Only wallets in `CRYPTO_NATIVE_LOGIN_ALLOWLIST` can still sign in. Each must already belong to a non-admin user, and the session works on RPC only. See [Configure Auth: OIDC only](/configuring/users/authentication#oidc-only). OIDC login registers the person automatically: the first time someone signs in with a valid token from the zone's OIDC provider, or from an organization's OIDC provider in multi-org mode, Prividium creates a user for them with no roles. There are two exceptions. Seeded pending organization admins get their organization's Admin role. Subjects listed in `OIDC_ADMIN_SUBS` who sign in through the zone's OIDC provider get the zone `admin` role at every sign-in, so removing that role does not last while the subject stays in the list. Anyone your identity provider issues a token to can therefore become a registered user, so control who can sign in at the identity provider. Check the [user onboarding](/developers/applications/user-onboarding-login) doc for more information about registering new users. A registered user can sign in, but registration alone does not grant access. Their roles, linked wallets, organization membership, and the action they are trying to take still decide what they can see or do. See [RPC Method Support](/rpc/rpc-support) and [Selective Disclosure](/configuring/contracts/selective-disclosure) for the public and authenticated RPC surfaces. ## How Does Prividium Decide Whether a Request Is Allowed? Prividium first identifies who or what made the request. Then it checks only the rules that apply to that request. Not every request involves a wallet. API calls can be allowed or denied from the caller's session, API key, roles, and scope without checking a wallet address. For example, an Admin API call may only need a session and an admin permission. A wallet-backed RPC call also needs a linked wallet. A contract call, event query, or organization-scoped action adds its own permission and scope checks. For an API, RPC, or M2M request, Prividium runs the checks below. Every check that applies must pass, and the order varies by route. On RPC, zone-level `full_sequencer_rpc_access` is checked first and skips the wallet and contract checks. 1. **Authentication:** The request presents a valid session token, API key, or allowed anonymous route. 2. **Session or API-key lookup:** The Permissions API loads the current user or M2M application from the database. For an allowed anonymous route, there is no user or M2M application to load. 3. **Wallet binding when a wallet is involved:** For wallet-backed RPC actions, the `from` address must belong to the resolved user, unless a trusted system permission explicitly bypasses that check. API requests that do not use a wallet skip this step. 4. **System permission check:** Route-level gates check permissions such as `admin_read`, `admin_write`, `contract_deployment`, `full_read_access`, or `org_rpc_access`. 5. **Contract or event permission check:** Contract calls and log queries evaluate the configured function or event rule for the target contract. Empty calldata sent to a contract runs its receive or fallback function, so it needs a rule on the `0x` selector. 6. **Organization-scope check:** In multi-org mode, organization-owned contracts and organization-only permissions must match the caller's organization context. See [System Permissions](/configuring/users/system-permissions) for the system-permission catalog and [Contract Permissions](/configuring/contracts/permissions) for function and event rules. :::details[Are Roles Additive, or Can One Role Deny Another Role?] Roles combine additively. If a user has multiple roles, Prividium uses the union of those roles' permissions. There is no deny role and no role-priority override. Removing access means removing the granting role or changing the permission rule that grants access. A role can carry system permissions, contract function permissions, and event permissions. It can belong to the zone or, in multi-org mode, to one organization. Organization scope is a boundary, not a deny role. A matching role can satisfy a `checkRole` rule, but it cannot cross an organization-only permission on a contract owned by another organization. Zone users with no organization are refused too. Zone-level bypass permissions such as `full_sequencer_rpc_access` are separate system permissions and should be treated as highly trusted operator access. ::: :::details[Does Prividium Deny Access by Default?] Yes, Prividium denies access by default for ordinary users. Contract functions and events are blocked until an admin configures an allow rule. Filtered RPC methods return only data associated with the caller's wallets unless the caller has an elevated read permission in the relevant scope. The main bypass is zone-scoped `full_sequencer_rpc_access`: users with that system permission skip contract-level permission checks at the RPC proxy and are forwarded directly to the sequencer RPC. An organization-scoped grant does not skip contract permission checks or the wallet-ownership check. It does allow direct deployments from the user's own wallet at the RPC proxy, and it widens read visibility to that organization's contracts and member wallets, like organization-scoped `full_read_access`. When the policy listener (`POLICY_PORT`) is enabled, the chain checks every transaction against `/admit` and `/judge`, including transactions from zone-level `full_sequencer_rpc_access` users, so their writes are still held to contract permissions on-chain. Their `eth_call` requests are not: Prividium sends them to the sequencer as `debug_traceCall`, which skips the policy listener. For other users, the chain checks `eth_call` against `/admit` and `/judge` as well. The listener needs a sequencer on protocol v31 or later. See [Policy: Where policy is enforced](/configuring/chain/policy#where-policy-is-enforced). Multi-org mode requires the listener: the Prividium API refuses to start with `MULTI_ORG_ENABLED=true` and no `POLICY_PORT`, unless `INSECURE_MULTI_ORG_WITHOUT_POLICY_ENABLED=true` is set. The built-in zone `admin` role includes `full_sequencer_rpc_access`, so the default zone administrator can bypass configured contract permissions at the RPC proxy. A custom admin role only gets this bypass if it explicitly includes `full_sequencer_rpc_access`. Organization admins are different. They can register and configure organization-only permissions for contracts in their own organization, but the built-in organization Admin role does not include `full_sequencer_rpc_access`. An organization admin still needs their own roles and wallets to satisfy the contract permission rule when they call the contract. A zone operator cannot lift this: an organization member can only hold their own organization's roles, and an organization-scoped `full_sequencer_rpc_access` grant does not skip contract permission checks. See [System Permissions: Full Sequencer RPC Access](/configuring/users/system-permissions#full-sequencer-rpc-access) for the bypass and [RPC Method Support](/rpc/rpc-support) for which methods are filtered. ::: :::details[When Do Role Changes Take Effect?] Role changes take effect on the next authenticated request. Sessions store the authenticated principal, but the API re-reads the user's current roles when it validates the session token. A user does not need to sign in again for a new role assignment or removal to affect authorization. Checks that run at sign-in are the exception. A user who gains `admin_write` during a session faces the passkey check only at their next sign-in, and a listed `OIDC_ADMIN_SUBS` subject gets the zone `admin` role back at their next sign-in. If the policy decision cache is enabled, the chain can keep using a cached `/admit` or `/judge` decision for up to its TTL. See [Building Web Applications: Session Management](/developers/applications/building-web-applications#session-management) for session lifetime and renewal behavior. ::: :::details[Can One Role Mix Zone-Level and Organization-Scoped Permissions?] A role itself belongs to one scope: either the zone or one organization. Zone operators can create zone-level roles with any system permission. Roles created from an organization context can only carry the organization-admin ceiling: `org_users_manage`, `org_wallets_manage`, `org_rpc_access`, `org_policy_access`, and the three `org_asset_instructions_*` permissions. The role editor offers a feature's permissions only while that feature is enabled. The ceiling applies to anyone using the organization context, including zone operators who switch into it. The built-in organization admin role carries organization-scoped `admin_read` and `admin_write`. A zone operator can still create an organization-scoped role outside the ceiling, such as an organization-scoped `full_read_access` role. They do this from the zone-level Roles surface by setting the role's organization, not from the organization context. ::: :::details[What Happens If a Zone Role Includes Organization-Oriented Permissions?] A zone-level role may include organization-oriented permissions such as `org_users_manage`. For an M2M application, that permission can satisfy organization-aware M2M checks for linked organizations. It does not make a user an organization admin by itself, and it does not remove the linked-organization or organization-scope checks. ::: ## What Is the Difference Between Zones and Organizations? A **zone** is the whole Prividium deployment. Zone-level resources apply across the deployment unless a feature explicitly narrows them. An **organization** is a scoped group inside the zone. Organizations group users inside a zone and, in multi-org mode, create separate admin and permission boundaries for organization admins, organization roles, organization-owned contracts, and organization-owned M2M credentials. | Scope | Managed by | Typical resources | | ------------ | ------------------------------------------ | --------------------------------------------------------------- | | Zone | Zone operators with zone-level admin roles | Global users, zone roles, zone contracts, zone M2M applications | | Organization | Organization admins or zone operators | Members, org roles, org contracts, org-owned M2M credentials | A **zone operator** is a user whose zone-scoped roles grant `admin_read`, plus `admin_write` to make changes. The built-in `admin` role grants both, and custom zone roles can grant them too. Registering zone contracts needs the built-in `admin` role. An **organization admin** manages one organization and cannot configure peer organizations or zone-level resources. In multi-org mode, an organization member, including an organization admin, can hold only roles from their own organization, so a zone user must give up zone roles before joining an organization. See [Manage Organizations](/configuring/chain/organizations) for organization setup, default roles, member management, organization contracts, org-owned credentials, and per-organization login settings. :::details[What Changes When Multi-Org Mode Is Enabled?] `MULTI_ORG_ENABLED` decides whether organizations are only grouping metadata or separate administrative and permission scopes. | Resource | `MULTI_ORG_ENABLED=true` | `MULTI_ORG_ENABLED=false` | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | Users | A user can belong to one organization or remain zone-level | Users can still belong to an organization | | Roles | Roles belong either to the zone or to one organization | Roles stay zone-level | | Organization admin role | Grants admin access only inside that organization | Organization admins cannot sign in, and organization roles are not available. Zone operators can still list and remove an organization's members | | Contracts | Contracts can belong to the zone or to one organization | Contract ownership has no effect on access | | Contract permissions | Organization-only permissions allow only members of the owning organization | Organization-only permission fields are not used | | Zone operators | Can manage zone resources and switch into organization context | Manage users, roles, contracts, and organizations from zone access | | Organization admins | Can manage only their organization's resources | Zone operators remain the administrators for the deployment | | M2M credentials | Zone operators can share credentials. Organization admins can own credentials, which act only after a zone operator links them | Org-owned credentials are unavailable; linked organizations still scope M2M user, wallet, and RPC actions | | Branding and wallet login | Each organization has its own user-panel branding and wallet login state. Zone operators set both from the Organizations page | Branding and wallet login stay zone-level | When `MULTI_ORG_ENABLED=true`, organization admins can create and assign organization roles, but only within the organization-admin ceiling described above, so they cannot grant zone-wide power. Organization membership does not grant chain access by itself. A member still needs roles that grant contract or system permissions. Zone-level roles can grant access across the zone. Organization roles grant access only inside their organization. When `MULTI_ORG_ENABLED=false`, organizations mainly group users for M2M access. Use the ordinary [Users](/configuring/users/managing-users) and [Roles](/configuring/users/roles) pages to manage user access. ::: :::details[Can a User Move Between Organizations?] A user can belong to at most one organization or remain a zone user. To move them, remove them from the current organization and then add them to the new one. Removing a user from an organization clears that organization's scoped roles from the user, but it does not delete the user or their wallets. See [Manage Organizations: Members](/configuring/chain/organizations#6-manage-organization-members). ::: :::details[Can a Zone User Call an Organization-Owned Contract?] If the matched permission is organization-only, no. In multi-org mode, organization-only permissions on organization-owned contracts can be used only by members of the owning organization. Users from peer organizations and zone-level users are denied. Zone users with `full_sequencer_rpc_access` skip contract permission checks at the RPC proxy, so their reads go through. When the policy listener is enabled, the chain still refuses their writes to an organization-only permission. If a zone operator creates a non-organization-only permission from the zone-level contract-permissions surface, the normal permission rule applies instead. ::: :::details[Can an Organization-Owned Contract Permission Reference a Zone Role?] Organization admins cannot reference zone roles from organization-scoped routes. Their function and event permissions are forced to `organizationOnly: true` and can reference only roles owned by that organization. A zone operator working from the zone-level permission surface can configure broader zone-level permissions when they intentionally open access outside the org boundary. ::: :::details[What Happens When a Zone Operator Switches Into an Organization Context?] The zone operator still acts as themselves. Prividium does not impersonate an organization admin or mint org-admin powers for that user. Zone-level `admin_read` or `admin_write` authorizes the organization-scoped route, but the organization-admin ceiling still applies to roles created there. When assigning roles to members, a zone operator can assign organization roles above the ceiling. Audit context records the active user and the organization id for `/organizations/:id/...` actions. ::: ## Who Can Manage Each Scope? Administration follows scope, and users and applications see only the admin surfaces, chain data, and resources their roles allow. :::details[Which Actors Can Access Which Administrative Areas?] | Actor | Can access | | ------------------- | -------------------------------------------------------------------------------------------------- | | Zone operator | Zone-level admin panel data and any organization they choose to manage | | Organization admin | One organization's members, roles, contracts, policy (when enabled), and org-owned M2M credentials | | Organization member | User panel features and contracts allowed by their organization-scoped roles and wallets | | Zone user | User panel features and contracts allowed by their zone-level roles and wallets | | User application | User-facing login flows; it acts with the signed-in user's token | | M2M application | Machine actions allowed by its roles, API key, IP whitelist, and linked organizations | The admin panel uses scope to decide which API routes it calls. In an organization context, it calls organization-scoped routes so an organization admin can manage only the resources they are authorized to see. An organization admin always works inside their organization context. ::: :::details[Who Creates the Organization Admin Role and Grants Organization-Scoped System Permissions?] The organization Admin role is a real scoped admin role, not just a label and not a zone admin role. A zone operator grants organization admin access by seeding an organization admin. Prividium creates or reuses that organization's Admin role when the pending admin first signs in. That promotion happens only when the first sign-in creates the account, so seed the admin before inviting them as a member. A zone operator can also assign the organization Admin role to an existing member. Organization admins cannot create arbitrary roles with `admin_read` or `admin_write`. They can delegate the built-in organization Admin role to another member because it grants no more power than they already hold. See [Manage Organizations: Delegation](/configuring/chain/organizations#8-what-an-organization-admin-may-delegate) and [Manage Users: Assign Roles](/configuring/users/managing-users#6-assign-roles-to-users). ::: :::details[Is `admin_write` the Same Thing as Write Admin Access?] Yes. Write admin access means `admin_write` in the relevant scope, so a **zone operator with write admin access** has zone-scoped `admin_write` and an organization admin has organization-scoped `admin_write`. ::: :::details[Does `admin_read` Let a Zone Operator See Everything in Explorer?] No. `admin_read` grants Admin Panel read access, but Explorer visibility comes from RPC read permissions. Chain-wide Explorer visibility requires zone-scoped `full_read_access` or `full_sequencer_rpc_access`. The built-in zone `admin` role holds every system permission the deployment defines. This includes `full_read_access` and `full_sequencer_rpc_access`, so it gets full Explorer visibility by default. A custom role with only `admin_read` does not. ::: :::details[Does `admin_write` Require MFA in Organization Scope?] Only after they register a passkey. When a user whose roles include `admin_write` has at least one passkey, Prividium requires a passkey assertion at login before it issues a session. A user with `admin_write` and no passkey signs in without MFA, because passkey registration is optional. This applies the same way whether `admin_write` comes from the built-in zone `admin` role or from an organization's Admin role, so encourage every admin to register a passkey. ::: ## Who Can Do Common Actions? Most actions require both the right actor and the right permission scope. Admin visibility, contract deployment, contract registration, RPC reads, and M2M queries each use different gates, so check the action before assigning a role. | Action or view | Who can access it | Notes | | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | [Deploy a contract](/configuring/contracts/contract-deployment) | A user with a linked wallet and a role carrying `contract_deployment`. `full_sequencer_rpc_access` also passes the RPC proxy, but not the policy listener | The Admin Panel deploy flow is for zone operators only and requires `VITE_TOKEN_DEPLOYMENT_ENABLED=true` | | [Deploy through an M2M application](/configuring/applications/m2m-applications#contract-deployment) | An M2M app with `org_rpc_access` and `contract_deployment`, and a signer user with `contract_deployment` (`full_sequencer_rpc_access` also satisfies either check at the RPC proxy, but not the policy listener) | Organization admins cannot grant `contract_deployment` | | [Register zone-level contracts](/configuring/contracts/permissions#2-register-a-contract) | Built-in zone `admin` users | [System contracts](/configuring/contracts/system-contracts) are registered automatically | | [Register organization contracts](/configuring/chain/organizations#7-organization-contracts) | Organization admins for their organization, or zone operators managing that organization | Organization-admin registration requires verifiable organization ownership | | [View registered contracts in the Admin Panel](/configuring/contracts/permissions#1-open-the-permissions-page) | Zone operators for the zone; organization admins for their organization | Organization admins do not see peer-organization contracts | | [Configure contract permissions](/configuring/contracts/permissions) | Zone operators for zone contracts; organization admins for their organization contracts | Organization admins create organization-only permissions and cannot configure peer organizations | | [View roles and user assignments](/configuring/users/roles) | Zone operators for zone users; organization admins for members of their organization | Zone user lists and organization member lists are separate | | [View all admin configuration read-only](/configuring/users/system-permissions#admin-read-access) | Users with `admin_read` in the relevant scope | Zone-level `admin_read` reads zone resources; organization-scoped `admin_read` reads that organization | | [Change admin configuration](/configuring/users/system-permissions#admin-write-access) | Users with `admin_write` in the relevant scope | `admin_write` users who have registered a passkey must pass MFA at login | | [Call public RPC methods](/rpc/rpc-support) | Anyone, only for methods marked public | Public methods do not load a user and do not grant access to filtered or permission-validated methods | | [Read selectively disclosed data](/configuring/contracts/selective-disclosure) | Anyone, only when selective disclosure is enabled for that data | Disclosure methods expose only the configured contract data | | [Read broad chain data through RPC or Explorer](/configuring/users/system-permissions#full-read-access) | Users with `full_read_access` or `full_sequencer_rpc_access` in the relevant scope | Zone-scoped access is chain-wide; org-scoped access is limited to that organization's visible data | | [See ordinary Explorer data](/getting-started/introduction/user-guide#how-does-the-block-explorer-work) | Signed-in users with at least one linked wallet | Standard users see wallet balances and transactions whose top-level sender or recipient is visible | | [See every account and transaction in Explorer](/getting-started/introduction/admin-guide#how-does-the-block-explorer-work) | Users with zone-level `full_sequencer_rpc_access`, such as the built-in zone `admin` role | Zone-level `full_read_access` alone shows every transaction and log, but not balances, nonces, or code of arbitrary wallets | | [See event logs](/configuring/contracts/permissions#5-configure-event-permissions) | Users or M2M apps whose roles satisfy the event permission | Event permissions are deny-by-default | | [Read contract metadata through M2M queries](/configuring/applications/m2m-applications#read-contract-metadata) | M2M applications with `contract_metadata_read` | This returns registered contract metadata through `/m2m-app-queries/contracts/:contractAddress`. A missing permission returns 404 | :::details[Who Can Deploy Contracts?] At the RPC proxy, either `contract_deployment` or `full_sequencer_rpc_access`, at zone or organization scope, allows a direct deployment from the user's own wallet. Zone-level `full_sequencer_rpc_access` also allows deploying from a wallet the user does not own. When the policy listener is enabled, which multi-org mode requires unless `INSECURE_MULTI_ORG_WITHOUT_POLICY_ENABLED=true`, deployments must also pass `/admit`. `/admit` checks the user who owns the signing wallet, and that user must hold `contract_deployment`; `full_sequencer_rpc_access` does not satisfy that check. For M2M deployment requirements, see the table above and [How Do Applications Fit Into the Model?](#how-do-applications-fit-into-the-model). Deploying through a factory contract is an ordinary contract call: it needs permission to call the factory's function, not `contract_deployment`. [Policy](/configuring/chain/policy) can also refuse a deployment. A published policy's default rule, while switched on, blocks any operation no allow rule matches, deployments included, even for a signer with `contract_deployment`. With organizations enabled, policy only governs organization members; zone users are not governed by any policy. A deployment can do more than an ordinary contract call. Treat `contract_deployment` as a trusted operator permission. Do not hand it out as an end-user convenience. See [Security Limitations](/developers/applications/security-limitations#3-contract-deployment-must-be-privileged) for the deployment-specific risk model. ::: :::details[Who Can Register and Configure Contracts?] Only the built-in zone `admin` role can register zone-level contracts; a custom role with `admin_write` is not enough. In multi-org mode, organization admins can register their own organization's contracts only when Prividium can verify organization ownership, for example through a Prividium deployment record tied to that admin or to a member of the same organization. Contracts without a verifiable ownership record require zone-operator review. See [Manage Organizations: Organization Contracts](/configuring/chain/organizations#7-organization-contracts). Contract visibility and contract permissions are different. Seeing a registered contract in the Admin Panel lets an admin inspect or configure its metadata and rules. Calling that contract through RPC still requires the caller's roles and wallets to satisfy the contract permission rule. ::: ## What Chain Data Can a User See? Chain-data visibility comes from filtered RPC reads, linked wallets, event permissions, and elevated read permissions. Organization membership can widen visibility only when the caller has an organization-scoped read role that allows it. :::details[What Counts as a Transaction Associated With a Linked Wallet?] Explorer data comes from filtered RPC reads. For ordinary users, a transaction is associated with a linked wallet when the wallet is the top-level transaction or receipt `from` address, or the top-level `to` address. Token-transfer recipients, event-topic addresses, and internal call participants do not make the whole transaction associated with the wallet. Internal calls do not widen Explorer visibility because trace methods such as `debug_traceTransaction` are forbidden. Event permissions and organization-scoped read roles are the exceptions: they can reveal a transaction that is not associated with any of the user's wallets, as described below. See [RPC Method Support](/rpc/rpc-support) for the filtered and forbidden method list. ::: :::details[Can Event Permissions Reveal Transactions That Are Otherwise Hidden?] Yes, partly. If a transaction is not associated with the user's wallets but emits a log that an event permission allows the user to read, Prividium returns that transaction in a redacted form: * Block results include the transaction. * The transaction object is returned with its `input` replaced by `0x`. The sender, recipient, value, and hash stay visible. * The receipt contains only the logs that the event permissions allow, plus logs from the contracts of an organization where the reader holds an organization-scoped `full_read_access` or `full_sequencer_rpc_access` role. A transaction that is associated with the user's wallet is not redacted: its receipt includes every log. Configure those rules on the [Contract Permissions](/configuring/contracts/permissions#5-configure-event-permissions) page. ::: :::details[Does `full_read_access` Respect Organization Boundaries?] `full_read_access` follows the scope of the role that grants it: * A zone-scoped `full_read_access` role is chain-wide for transactions, receipts, blocks, and event logs, and it bypasses event permissions. Balance, nonce, and code lookups (`eth_getBalance`, `eth_getTransactionCount`, `eth_getCode`) for arbitrary wallets stay blocked; those need `full_sequencer_rpc_access`. * An organization-scoped `full_read_access` role expands visibility to that organization's contracts and member wallets. Transactions sent from or to a member's wallet appear in lookups by hash, receipts, and block listings, and balance, nonce, and code lookups work for member wallets and the organization's contracts. `eth_getLogs` only widens to the organization's contracts: a log from a zone contract that names a member's wallet stays hidden there unless an event permission allows it. Receipts for transactions sent from or to a member's wallet are returned whole, the same as receipts for the reader's own transactions, so they can include logs from zone or peer-organization contracts that the transaction touched. Otherwise, the role does not cross into peer organizations, and it does not make zone contracts visible unless the user's own wallet is otherwise associated. Organization-scoped `full_read_access` is outside the organization-admin ceiling, so only a zone operator can create it, from the zone-level Roles surface. See [System Permissions: Full Read Access](/configuring/users/system-permissions#full-read-access) and [Manage Organizations: Delegation](/configuring/chain/organizations#8-what-an-organization-admin-may-delegate). ::: :::details[Can a User See Other Members of Their Organization or Their Wallets?] Organization membership does not let a normal user browse the organization's member list or wallet assignments. Directory-style admin data requires `admin_read` in the relevant scope. The organization Admin role includes it. An org-scoped full-read role affects chain and RPC visibility; it does not grant Admin Panel access to user records. See [Manage Users](/configuring/users/managing-users) for user and wallet administration. ::: ## How Do Wallets Affect Access? Wallets prove which on-chain address a user controls. They do not grant permissions by themselves. After Prividium links a wallet to a user, that wallet uses the user's roles for contract calls and per-user RPC authorization. Roles and permission rules still decide what the wallet can do. Each user can have multiple wallet addresses. All linked wallets inherit the user's effective permissions, so adding a wallet to a user does not grant new contract permissions. :::details[How Does a User Prove They Control a Wallet?] Prividium supports two wallet-linking paths: * **User self-service:** The authenticated user requests a Sign-In with Ethereum (SIWE) association challenge, signs the message with the wallet, and submits the signature. Prividium verifies the nonce, domain, expiration, user binding, and wallet address before linking the wallet. * **Admin or backend-assisted onboarding:** A trusted administrator or backend can create or update a user with wallet addresses directly. In that flow, the trusted caller owns the proof step before it writes to Prividium. See [User Onboarding and Login](/developers/applications/user-onboarding-login). Self-service wallet association is one-time proof for the link. Prividium does not periodically re-verify linked wallets. To prove control again, unlink the wallet and run the association flow again. ::: :::details[Can the Same Wallet Address Belong to Two Users?] An active wallet address can belong to only one user at a time. This uniqueness applies across the whole zone, including users in different organizations. To move a wallet to another user, unlink it from the current user first. ::: :::details[Can a Wallet Be Unlinked, and What Happens to Pending Authorizations?] Users can unlink a wallet from their own account, and admins can remove wallet addresses while editing a user. Unlinking the wallet stops new authorizations for that address because future requests no longer see the address on the user. When a user tries to create a new Per-User RPC transaction authorization for an unlinked address, Prividium rejects it because the wallet address is not associated with that user. Existing Per-User RPC transaction authorizations are short-lived rows tied to the user, wallet, nonce, calldata, target, and value. They expire 1 hour after they were last created or refreshed. Authorizing the same wallet and nonce again replaces the authorized transaction and restarts the 1-hour window. For a contract call or a value transfer to a contract, Prividium checks the contract permission again at send time, including that the wallet still belongs to the user, so unlinking the wallet blocks it immediately. A native transfer to an address without code and a contract deployment are not checked against wallet ownership again. They stay usable until the authorization expires. To cut off tokenized wallet RPC access at once, rotate the user's wallet RPC token. See [Per-User RPC: Transaction Authorizations](/rpc/per-user-rpc#transaction-authorizations). ::: :::details[Can Smart-Contract Wallets or Multisigs Be Linked?] Smart-contract wallets and multisigs can be linked when they can prove control. The contract must already be deployed. Prividium calls its EIP-1271 `isValidSignature` with an EIP-712 hash of the association message, and the call must return exactly the EIP-1271 magic value. A revert or any other return value fails the association. A multisig must produce a signature that its contract accepts for that hash. An ordinary externally owned account signature is not enough to link a contract address. Wallets that cannot satisfy EIP-1271 cannot complete self-service association. ::: :::details[How Does Per-User RPC Use Wallets?] Prividium creates a transaction authorization only when the requested `walletAddress` is currently linked to the signed-in user. The Per-User RPC token then identifies that user when the transaction is sent. The API response returns only a success message and an `activeUntil` timestamp. See [Per-User RPC and Transaction Authorizations](/rpc/per-user-rpc) for the detailed flow and [Manage Users](/configuring/users/managing-users#5-link-multiple-wallets) for wallet assignment. See [Configure Auth](/configuring/users/authentication) for OIDC and wallet-login setup. ::: ## How Do Applications Fit Into the Model? Applications decide how callers enter Prividium. [User applications](/configuring/applications/web-applications) carry browser login configuration and act for the signed-in user through a session bound to the application. [M2M applications](/configuring/applications/m2m-applications) authenticate as machine principals and use their own API keys, roles, allowlists, and organization links. :::details[What Does an M2M Application Authenticate As?] M2M applications authenticate as machine principals with API keys. They do not sign in as users, and they do not create browser login sessions. An M2M application's access depends on: * The roles assigned to the M2M application, including zone-level system permissions * Its active API keys * Its IP whitelist * The organizations linked to it * For an org-owned credential, an owner organization that still exists For example, an M2M application with `org_users_manage` can create and list users only in its linked organizations. An application with `org_wallets_manage` can attach wallets to those users, and creating a user with wallets in one call needs both. An application with `org_rpc_access` can make RPC calls on behalf of users in any linked organization. Linking an M2M application to an organization does not grant user login. It only scopes what the machine principal may do through organization-aware M2M permissions. ::: :::details[When an M2M Application Calls RPC on Behalf of Users, Whose Permissions Apply?] When an M2M application calls RPC on behalf of organization users, Prividium does not simply union app and user permissions. The checks depend on the RPC action: * **Contract reads and writes:** The M2M app must have `org_rpc_access`, the `from` wallet must belong to a user in one of the app's linked organizations, and that user's roles must satisfy the contract function permission. The app's roles open the M2M path; the user's roles decide the contract method access. A transfer to an address without contract code only checks that the signer is a wallet in a linked organization. * **Contract deployment:** The M2M app must have `org_rpc_access` and `contract_deployment`, the recovered signer user must have `contract_deployment` (`full_sequencer_rpc_access` also satisfies either check), and the signer must be a wallet of a user in a linked organization. * **Event queries:** The M2M app must have `org_rpc_access`; Prividium checks the M2M app's roles against event permissions and uses linked-organization wallets as the address context. Individual user roles are not checked for event queries. An app with zone-level `full_read_access` or `rpc_read_eth_getLogs` reads all logs without these checks. An M2M app with zone-level `full_sequencer_rpc_access` skips the read and write checks above. Deployments still follow the deployment rule. ::: :::details[Can an M2M Application Be Linked to Several Organizations?] Zone operators can create zone-level M2M applications and link them to organizations. In multi-org mode, organization admins can also create org-owned M2M credentials for their own organization. Zone-level M2M applications can link to several organizations. Among organizations, only the owner organization lists and manages an org-owned credential. Zone operators can also see and manage it. Organization admins cannot link it to any organization, including their own. Ownership alone does not let a credential act. Organization-aware M2M actions and RPC calls on behalf of users only use the credential's organization links, and a new org-owned credential has none. Until a zone operator links it, an org-owned credential cannot create users, attach wallets, or make RPC calls for users, even in its owner organization. Zone operators can link any credential, including an org-owned one, to any organization from the zone-level M2M settings. Be careful when linking an org-owned credential to a peer organization. Its `org_*` user and wallet actions still fail there while its roles belong to the owner organization. RPC calls on behalf of the peer organization's users do follow the link: the credential's `org_rpc_access` opens the path, and the peer user's roles decide contract access. ::: :::details[How Do API Key Rotation, Revocation, and IP Allowlists Work?] API keys belong to one M2M application. Rotation means creating a new key, updating the integration to use it, then revoking the old key. Revoked keys stop working immediately, and expired keys fail authentication automatically. The IP allowlist belongs to the M2M application, not to each key, so every key for that app uses the same source-IP rules. Every key has an expiry date, at most one year by default. An empty IP allowlist rejects every request. See [M2M Applications](/configuring/applications/m2m-applications) for setup details. ::: :::details[Does a User Application Have Permissions of Its Own?] User applications are OAuth clients for browser login. They configure redirect URIs, a whitelisted browser origin, and public listing metadata, and Prividium assigns each one an OAuth client ID. They do not hold Prividium roles or contract permissions of their own. After login, the application gets a session bound to its OAuth client ID, not the user's own session. That session works only on RPC, profile, wallet, contract ABI, and session endpoints; admin endpoints reject it. Within those endpoints, the user's organization, roles, wallets, and contract permissions decide what succeeds. The application's redirect URIs and whitelisted origin control where login callbacks and browser requests may come from; they do not grant chain access. See [Web Applications](/configuring/applications/web-applications) for the admin configuration and [Building Web Applications](/developers/applications/building-web-applications) for the login flow. ::: ## Next Steps | Task | Where to go | | ---------------------------------- | -------------------------------------------------------------- | | Configure sign-in methods | [Configure Auth](/configuring/users/authentication) | | Add users and wallets | [Manage Users](/configuring/users/managing-users) | | Create roles | [Manage Roles](/configuring/users/roles) | | Review system permissions | [System Permissions](/configuring/users/system-permissions) | | Create and manage organizations | [Manage Organizations](/configuring/chain/organizations) | | Configure contract access | [Contract Permissions](/configuring/contracts/permissions) | | Configure machine principals | [M2M Applications](/configuring/applications/m2m-applications) | | Configure user-facing applications | [Web Applications](/configuring/applications/web-applications) |