> For the complete documentation index, see [llms.txt](https://docs.t-rex.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.t-rex.network/identity-onchainid/keys-purposes-and-signers.md).

# 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](/identity-onchainid/an-identity-that-is-also-an-account.md).

| 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.

```mermaid
flowchart TB
    E["A key calls execute(to, value, data)"] --> P{"Does the key hold<br/>any purpose that may propose?"}
    P -- "no" --> X["Refused"]
    P -- "yes" --> Q["Request queued"]
    Q --> A{"May this key<br/>run it alone?"}
    A -- "MANAGEMENT: always<br/>ACTION: if the target is another contract" --> R["Runs at once"]
    A -- "otherwise" --> W["Waits"]
    W --> AP{"approve(id, true)<br/>by an authorized key"}
    AP --> R
    W --> RJ["approve(id, false): closed"]
```

* **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](/identity-onchainid/account-abstraction-and-recovery.md).

## 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.                                                                      |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.t-rex.network/identity-onchainid/keys-purposes-and-signers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.