Keys, purposes and signers

An ONCHAINID is controlled by keys. A key is a signer registered on the identity with one or more purposes. The purposes are the identity's authorization model: they decide who manages the identity, who acts for it, who adds claims to it. This page describes the purposes, what each can reach, the kinds of signer a key can be, and the queue that lets one key propose and another approve.

What a key is

A key record has four parts.

Part	Meaning
Signer data	The ERC-7913 representation of the signer. Twenty bytes for an address: an externally owned account or a smart-contract wallet. Longer for any other scheme: the address of a verifier contract followed by the public key.
Key hash	keccak256 of the signer data. It identifies the key in every function and event.
Purposes	One or more of the six purposes below.
Key type and client data	Descriptive metadata: a label for the scheme, and data a client needs to use the key, for example a WebAuthn credential identifier. Neither takes part in verification.

A key is always scoped to one identity. The same signer can be a key on several identities, with different purposes on each.

The six purposes

Purpose	Value	What the key can do
MANAGEMENT	1	Everything. Add and remove keys, install and remove modules, link and revoke wallets, and anything a lower purpose can do. A MANAGEMENT key satisfies every purpose check.
ACTION	2	Make the identity call other contracts, which includes transferring the tokens it holds. Sign as the identity. Approve queued calls to other contracts.
CLAIM_SIGNER	3	On the identity of a Claim Issuer: sign the claims the issuer attests. On any identity: add claims to it and remove claims from it.
ENCRYPTION	4	Hold encryption material for use outside the chain. It carries no on-chain authority.
CLAIM_ADDER	5	Add claims to the identity. It cannot remove them.
PROPOSER	6	Queue a call for approval. It cannot run one or approve one.

What each purpose can reach

Authorization depends on the target of a call.

Target of the call	Purpose required	Why
The identity itself: addKey, removeKey, installModule, uninstallModule	MANAGEMENT	These change who controls the identity.
The IdentityFactory: linkAccount, revokeAccount, settlePendingCrossChainLink	MANAGEMENT	These change which wallets belong to the identity. A revocation is permanent.
The key registry module	MANAGEMENT	A call to it rewrites the identity's own keys.
Any other contract, for example a token	ACTION	The identity acts toward the outside.
addClaim on the identity	CLAIM_SIGNER or CLAIM_ADDER	By a direct call from the key holder.
removeClaim on the identity	CLAIM_SIGNER	By a direct call from the key holder.

The same rule is applied wherever a call is authorized: by the validator for user operations, by the account for calls dispatched by a module, and by the execution queue. An ACTION key has no route to a management operation through any of them.

Signers

A key is not tied to one signature scheme. The identity recognizes signers through ERC-7913, which gives every scheme one representation and one verification interface.

Signer	Signer data	How a signature is verified
Externally owned account	The address	ECDSA recovery
Smart-contract wallet, multisig	The address	ERC-1271, by calling the wallet
Passkey, platform authenticator (WebAuthn)	Verifier address, then the public key	By the verifier contract
RSA key	Verifier address, then the public key	By the verifier contract
A scheme added later	Verifier address, then the public key	By its verifier contract

Supporting a new signature scheme means deploying a verifier for it. The identity does not change.

Two kinds of key never sign.

• Module keys. When a module is installed with a purpose, its address is registered as a key of type MODULE. The key lets the module dispatch calls for the identity within that purpose. It cannot sign a user operation or a signature.

• Governance as a key. A key can be the address of an OpenZeppelin AccessManager. The identity is then governed through roles rather than through one signer. The ONCHAINID of a token is managed this way, by the AccessManager of its token suite.

Which path a signer uses

An identity acts through a user operation or through a direct call. See An identity that is also an account.

Signer	User operation	Direct call
Externally owned account	Yes	Yes
Smart-contract wallet that implements ERC-1271	Yes	Yes
Contract that does not sign, for example an AccessManager	No	Yes
Passkey, RSA key, any verifier-based signer	Yes	No

A direct call is authorized from the address of the caller, so only a key that is an address can make one. A passkey has no address. It acts through user operations. Conversely, a contract that cannot produce a signature acts through direct calls only.

In a user operation, the signature field carries the signer data and the signature together, so the validator knows which key claims to have signed before it verifies anything. A signer that is not a registered key of the identity is rejected without any signature check.

The execution queue

The ERC-734 execute and approve functions let an identity separate proposing a call from approving it. The KeyApprovalModule holds the queue.

• Proposing. A key holding PROPOSER, ACTION, CLAIM_SIGNER, CLAIM_ADDER or MANAGEMENT can queue a request. An address with no key on the identity cannot.

• Running at once. A request from a MANAGEMENT key runs immediately. A request from an ACTION key runs immediately when its target is another contract. Every other request waits.

• Approving. A request targeting the identity, the factory or the key registry is approved by a MANAGEMENT key. A request targeting another contract is approved by an ACTION key.

• The proposer is remembered. Approval checks that the key that proposed the request can still propose. A request from a revoked key cannot run. Any authorized approver can still reject it.

• The outcome is recorded. A request is marked as attempted, and separately as succeeded or not, so a failed call is not mistaken for a successful one.

• Uninstalling voids the queue. Every pending request is cancelled when the module is uninstalled, so none can reappear after a reinstall.

execute and approve must be called directly on the identity by the key holder. They are not reachable through a user operation or a relayed call.

A typical use: an automated system holds a PROPOSER key and queues payments or transfers, and an operator holding an ACTION key approves them.

Managing keys

Operation	Rule
Add a key, or add a purpose to a key	addKeyWithData registers a signer with its data. addKey adds a purpose to a signer that is already registered. Both require MANAGEMENT.
Remove a purpose from a key	removeKey(key, purpose), by MANAGEMENT. When its last purpose is removed, the key record is deleted.
The last manager	The last MANAGEMENT key that can sign cannot be removed. Module keys do not count, so an identity cannot be left with a module as its only manager.
Several devices	An identity can register several keys with the same purpose: a passkey per device, or an operations team.
Audit trail	KeyAdded and KeyRemoved name the identity, the key, the purpose and the caller. KeyUsed records which key validated a user operation.

Losing every MANAGEMENT key locks the identity. The RecoveryModule exists for that case and is described in Account abstraction and recovery.

Choosing a key set

Owner	A reasonable starting point
Individual investor	A passkey with MANAGEMENT on the main device and a second passkey on another device. Guardians for recovery.
Institution	MANAGEMENT held by a multisig or an AccessManager. ACTION keys for operations desks. PROPOSER keys for automated systems.
Claim Issuer	MANAGEMENT held by governance. Dedicated CLAIM_SIGNER keys for the signing service, rotated without touching MANAGEMENT.
Token	MANAGEMENT held by the AccessManager of the token suite.