The access manager checks the caller's role grant on chain, not anything a screen shows, and a missing or revoked role makes the call revert with no change.
A role grant lives in an access manager: the organisation's system access manager, one token's own, or an add-on's own. That manager alone decides whether the caller holds the role, except for five system roles that only the platform checks. System manager and Auditor sit in the system access manager, Custodian and Supply management in a token's, and authority in one gives none in another. Offering roles are token roles on the token an offering sells.
A grant through the platform can name a person instead of one address, and the change then reaches every wallet the organisation can act on for that participant. A grant can carry an end. At that time the platform sends the revoke, and the role stays held until that transaction lands.
Before any chain write, the platform refuses a grant that pairs Auditor with another system role. Once the organisation enables its segregation rules, it also refuses a grant that breaks one of them, and a rule set to warn lets the grant through once it carries a written reason. A grant made directly on chain skips both checks. A Console screen and an on-chain role check are two different systems, so a button appearing does not mean the transaction behind it succeeds.
Why a role grant matters
A role grant records on chain who can mint, freeze or change the rules, and the access manager enforces that record. For most roles a contract checks the grant. Five system roles unlock Platform API and Console actions only, and no contract function checks them. The five are Gas manager, Verification issuer, Asset designer, Bank rail manager and Auditor.
After issuance, each operation an issuer runs on an asset is a call that a role gates, such as minting, freezing a holding, pausing the token or changing its compliance modules. Asset Lifecycle lists these operations, and each one checks a role grant.
The platform splits authority into named roles. An Asset manager can deploy and configure a token. A separate Funds manager withdraws what an offering collects, and the Offering admin runs the sale. One person can hold both, unless the organisation enables the segregation rule that keeps them apart. An Auditor reads permissions, identities, audit logs and system state, and has no power to change anything.
To find who can move client funds, read the access managers' own records, the same records the chain enforces. Look for Custodian and Supply management in each token's access manager, and for Identity manager and System manager in the system access manager: an Identity manager names the replacement wallet in a recovery, and a System manager replaces the logic every token runs.
Who can do what, day to day
A role grant decides which team member can complete which task, whether the role is a system role like Asset manager or an asset role like Custodian. The Console shows each role under its label, and the Platform API names it by a field such as tokenManager for Asset manager or admin for Permission manager. Roles and segregation of duties lists every role.
System manager bootstraps the deployment and manages upgrades. Identity manager registers and recovers identities, and the separate Organisation identity manager manages the organisation's own identity. Asset manager deploys and configures tokens. Verification issuer attaches identity claims, though holding that role alone does not make an address a trusted source: trust is a separate decision made in the trusted issuers registry. Gas manager funds and configures the paymaster, the contract that pays network fees for sponsored transactions. Rotating the paymaster's signing key needs System manager. The Platform API and the Console check Gas manager, and no contract does. The paymaster's own withdrawal and stake operations are gated on chain by System manager, not Gas manager, because they move funds out of the paymaster.
A revoke takes effect when its transaction confirms. After it, the next call that the role would have covered fails, including a retry of a request already queued. The person is not signed out. For a role a contract checks, the block happens when the transaction reaches the access manager. For a role only the platform checks, it happens once the platform's record of the chain shows the revoke.
Two access managers, not one
Two kinds of access manager hold the platform's own role grants: one system access manager for the organisation's system roles, and one per token for that asset's own roles. Add-ons such as a trading venue keep a third kind, covered below. A single address can hold broad authority in one and none in the other, and the contracts do not mirror each other's grants.
The system access manager is a single upgradeable contract. It holds the 15 system roles that the Console and the Platform API grant to a person, among them Permission manager, System manager, Asset manager, Compliance manager, Identity manager, Verification issuer and Auditor. It also holds Organisation identity manager, which the system grants to the account that bootstraps it, and the module roles that platform contracts grant each other during bootstrap. The token access manager is the equivalent contract for one token's seven roles: Permission manager, Governance, Supply management, Custodian, Emergency, Offering admin and Funds manager. Each one sits behind its own proxy, which the token factory deploys with the token. The factory holds the administrator role and Governance only while it deploys the token, and renounces both as the last step of the deployment. When the organisation switches to smart wallets, the switch also grants the organisation's own wallet the system roles its signer held. That wallet belongs to the organisation's participant, not to a person, so the Console lists it under the organisation's name and does not count it as a person. Anyone who can work as the organisation, a holder of Organisation identity manager or Permission manager, then sends requests from that wallet with those roles.
Offering roles have no access manager of their own. Offering admin and Funds manager are token roles held on the access manager of the token the offering sells. So a grant from an offering's page covers every offering of that token, and a sale has no role record of its own.
Both managers build on the same access-control foundation. Granting and revoking a role is itself gated: a caller needs the target role's admin role. In the system access manager, that admin chain is walked back to DEFAULT_ADMIN_ROLE, the one role that can set every other role's admin. In a token's access manager, DEFAULT_ADMIN_ROLE is the admin of every role directly. The Console calls DEFAULT_ADMIN_ROLE Permission manager.
Add-on contracts can define their own narrower role sets, granted through an access manager owned by the add-on. In the Trading Venue add-on, each venue splits the operator who configures instruments from the submitter that settles trades, each function gated by its own role check. Nothing on chain stops a venue administrator granting both roles to one address. This pair is one of the platform's default segregation pairs, so the platform refuses that grant through its own routes once the organisation enables its segregation rules. The submitter role belongs to the organisation's operations signer, and the operator role to the person who configures the venue.
A caller also reaches the two managers in different ways.
System access manager
One upgradeable instance for the whole deployment. A caller reaches it directly. Its own DEFAULT_ADMIN_ROLE chain is the only one that can grant System manager, Auditor, Gas manager and the other system roles.
Token access manager
One instance per token, deployed behind its own proxy with the token, which resolves its logic through the system contract. The initial administrator named when the token is created holds DEFAULT_ADMIN_ROLE on it from the start.
Holding a role in one gives no authority in the other: an Asset manager still needs a role in a token's own access manager to act on that token directly.
A grant reaches every wallet of a person
The platform records each person as a participant, and a participant can hold more than one wallet: a signing wallet and, in an organisation that uses smart wallets, the smart wallet that executes their transactions. A role grant through the platform names the participant, and the platform sends the grant to every wallet it can act on for that person. A grant can still name one address instead, for a wallet that belongs to no participant or when only one wallet should change.
The access manager checks the wallet that makes the call, so a role the signing wallet holds does nothing for a transaction the smart wallet executes. The Console marks a person whose smart wallet lacks a role their signing wallet holds as “Out of sync”, and a Permission manager copies the missing roles across.
Time-bound grants
Use an end for temporary authority, such as a cover Custodian for a holiday or an Auditor for one review. The Platform API accepts an end at least one minute after the request, and the Console asks for two minutes. The platform records the end and, when it passes, a platform workflow revokes the role on chain. The contract itself does not end the role: the revoke is a transaction the platform sends. On an asset, a grant sent again with a later end, or without one, replaces the earlier end. For an asset role, the platform also sends a webhook event when the end is less than 24 hours away and another after the revoke.
On an asset, every role is administered by DEFAULT_ADMIN_ROLE, so the platform checks the chain when the end passes and signs the revoke with the first wallet it holds keys for that still holds DEFAULT_ADMIN_ROLE: the wallet that granted the role, then the signer of another time-bound grant on the same asset, then the organisation's operations signer. A granter that has since lost DEFAULT_ADMIN_ROLE therefore no longer blocks the revoke. When none of those wallets administers the asset, nobody the platform can sign for may revoke the role: the platform sends no transaction, raises an operator alert and checks again after a backoff, so the role stays held until one of them administers the asset again or someone revokes it by hand.
Before it signs a revoke, the platform checks its transaction queue for a grant of the same role to the same account that is still being written, from any signer. While one is, the platform sends no revoke and checks again every minute, and it withdraws a revoke it queued earlier that has not been submitted yet. A grant that lands replaces or closes the expiry. A grant that fails lets the revoke go ahead. A revoke that was already submitted cannot be withdrawn. A grant of the role that lands after the platform queued its revoke also withdraws that revoke if it has not been submitted yet, even when the grant changed nothing on chain because the account still held the role. A permanent grant ends the expiry, and a grant with a later end keeps only that later end.
Permission manager has one extra rule on a token. Through the platform, a holder whose own Permission manager role has an end cannot grant Permission manager, and the platform refuses a change that would leave the token with no Permission manager whose role has no end.
Segregation of duties
Every role grant route of the platform checks the grant against the roles the wallet already holds, before any chain write. The check compares wallets, not people, so one person can hold both roles of a pair on two wallets. One rule applies in every organisation: a wallet cannot hold Auditor together with any other system role the platform grants. Each organisation can also keep its own pairs of roles that one wallet may not hold together, such as Supply management and Custodian, or Offering admin and Funds manager. Each pair is set to refuse the grant, or to let it through with a written reason that the audit trail keeps. The platform ships seven default pairs and applies them only after the organisation saves and enables its rules.
The check guards the platform's routes, not the contract. A grant made directly on chain outside the platform is not checked, so the platform also lists every wallet that holds a pair the organisation's rules name, from its record of role holdings. That report does not cover the Auditor rule. The Roles and segregation of duties reference lists the roles, the default pairs and the modes, and Roles and permissions shows how a Permission manager reviews, grants and revokes roles in the Console.
Role changes need a Console sign-in
System, asset, offering and venue role grants and revokes through the Platform API require a Console-issued session, in both API v1 and API v2. The same rule applies to custody gateway role grants and revokes, fixed-yield schedule withdrawals, and the asset routes that add or remove supply delegates, hold reservers and authorised converters or revoke a burner capability. The v1 routes answer the refusal as their existing 403 DALP-9485, because v1 declares no other answer. The message and fix text in that response say to sign in to the Console, not to request a token role. A session issued by the Investor portal, an anonymous session or a session with no recorded issuing app answers 403 Forbidden with WALLET_ (DALP-200384). No role change starts. Sign in to the Console and retry. Sessions issued before this check recorded their issuing app are refused the same way until the user signs in to the Console again. The check applies whether or not an identity provider is configured. This refusal says nothing about whether the wallet holds the role needed to make the change: that check still applies after sign-in. API keys remain accepted where the route permits them.
Checking a role before you rely on it
has is a plain view call against whichever access manager holds the role, and every governed contract exposes accessManager() so a caller can find the right instance without guessing. Read hasRole on chain for the exact current answer, or read the platform's indexed access-control views, which resolve the same roles into named flags for a faster lookup that can lag the block a change landed in. Check one of the two before submitting a transaction that depends on the answer: a role-management call from a caller who lacks the target role's own admin role reverts with the access manager's unauthorised-account error. Recover by reading getRoleAdmin(role) for the admin role that can grant it, following that chain back to DEFAULT_ADMIN_ROLE if needed, and asking a holder of that role to act.
Every role identifier but one is a hash of a name, defined once as a constant so integrations reference the constant rather than recompute the hash. The exception is DEFAULT_ADMIN_ROLE itself, the zero value OpenZeppelin's access-control base reserves. Two shapes of batch helper exist: one applies one role to a list of addresses, gated the same as a single grant or revoke, and the other applies a list of roles to one address. On the system access manager, that second shape is gated to DEFAULT_ADMIN_ROLE specifically, stronger than a single role's own admin check. A caller who can grant one role at a time can still be refused the multi-role helper. The token access manager's equivalent has no such extra gate. Confirm which manager and which helper you are calling before assuming one caller can use both the same way.
Renouncing a role, including through the multi-role helper, lets a holder remove their own permission, and an authorised administrator can grant it again. The last DEFAULT_ADMIN_ROLE holder is different: without one, no account can grant or revoke the roles that DEFAULT_ADMIN_ROLE controls. So an access manager that counts its DEFAULT_ADMIN_ROLE holders refuses any revoke or renounce that would leave none, with LastAdminProtected. A token's access manager counts from the moment the token is created. A token created before counting existed starts once one of its administrators seeds the count. Until then, a direct contract call can still remove its last holder, so confirm another holder exists before removing one. A system's access manager that has not counted its holders yet refuses any change to who holds DEFAULT_ADMIN_ROLE with AdminCountNotInitialized, until an account allowed to upgrade it, a holder of DEFAULT_ADMIN_ROLE or System manager, seeds the count. Separately administered roles keep their own configured administrators regardless.
A role check inside a sponsored call checks the real caller, not the trusted forwarder that relays it. The system access manager also exposes hasAnyRole, a set-membership read some of its own gated functions use internally. The token access manager has no equivalent, so a caller checking a per-asset role checks hasRole once per role instead.
On-chain role, organisation role, delegated authority
An on-chain role, an organisation role and delegated authority are three different things. The access manager checks only the on-chain role before a privileged call runs.
An on-chain role lives in an access manager and is checked at the moment of the call. A missing or revoked role reverts the transaction, and a present role passes only this check, so other checks can still reject the call. The organisation role, Owner or Member, and the platform role, Administrator or Member, decide which organisation and platform actions a signed-in person can take, such as changing settings or inviting people, and grant no contract authority. An organisation owner who must sign a mint still needs Supply management on a wallet the organisation can act on for them. Most Console controls that lead to a contract call read the platform's indexed view of the on-chain roles, which follows new blocks rather than the chain head. So a screen can show a control to someone whose role was revoked a moment ago, and the underlying call still reverts.
Delegated authority is a separate model. Working as another participant sets whose context an operator steps into, and grants that operator no role. The on-chain roles of the account that executes the call decide what the operator can then do, as if the operator held those roles directly. A reviewer who asks who can do a given task takes the answer from the access manager, not from which party someone was acting as.
Frequently asked questions
Does a role apply to every asset, or to one?
An asset role applies to one asset. Per-asset roles, like Custodian or Governance, are checked against a single token's own access manager, so holding Custodian on one security token grants no authority on a second token deployed later, even under the same organisation. A system role applies across the organisation's system. A role an add-on defines, such as a Trading Venue's operator and submitter roles, is checked in that venue's own access manager and grants no authority on another venue.
What happens to work already underway when a role is revoked?
A revoke does not undo a transaction that passed the access manager's check before it. The platform's record of the chain lags the chain itself: the revocation first lands as a provisional event, access-, and can be followed by a retraction, access-, if a chain reorganisation reverses the block it was read from. A grant follows the same two-stage lifecycle. Store the event ID, idempotency key, role, account, and access manager address so a retraction updates the same record instead of creating a duplicate.
Who can upgrade the access manager contracts themselves?
The system access manager authorises its own upgrade: the call needs DEFAULT_ADMIN_ROLE or System manager, checked on that same contract, and the upgrade can install any implementation. The token access manager has no equivalent function of its own. Its proxy resolves its logic address from the system contract on every call, and only System manager can change that registered implementation. Every token access manager on the deployment upgrades when it changes, and no token's own Permission manager can move or block that change. A holder of System manager controls the permission logic of every token on the system, and also replaces, each in one call, the token logic of every token a factory deployed, every add-on access manager and every custody gateway. Keep System manager, like Permission manager, on as few accounts as possible.
Who grants the very first role on a new deployment?
The access manager grants DEFAULT_ADMIN_ROLE to a fixed list of initial admin addresses at deployment, before any other role exists. From there, DEFAULT_ADMIN_ROLE, or a role it delegates admin authority to, grants every other role. The system access manager and each token access manager hold their own separate instance of that chain, and an admin on one contract has no authority on the other. The token factory is among the initial administrators of a token's access manager only for the deployment, and renounces the role before the token is handed over.