Signer
A signer represents a digital identity in the ledger. Every operation requires authorization from a signer, establishing who is acting and ensuring accountability.
The recommended approach is to generate a key pair locally and register only the public key with the ledger. This allows the server to verify requests signed by the corresponding private key, without the private key ever leaving the client. If a private key is included in the request, it must be encrypted client-side — the server stores it as-is and cannot decrypt it.
System-managed signers such as system have their keys generated and encrypted by the server automatically.
Each signer can authenticate through one or more factors like cryptographic key pairs for direct signing or client credentials for OAuth tokens. Signers can also carry metadata like security constraints or links to external identity systems.
Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /signers | Register a new digital identity in the ledger. |
| GET | /signers | Query signers with filtering, sorting, and pagination. |
| GET | /signers/{id} | Retrieve a signer by its handle or LUID. |
| PUT | /signers/{id} | Submit a new version of a signer. |
| POST | /signers/{id}/proofs | Submit a signed proof to a signer record. |
Factors
| Method | Path | Description |
|---|---|---|
| POST | /signers/{signer}/factors | Add a new authentication factor to a signer. |
| GET | /signers/{signer}/factors | Query authentication factors for a signer with filtering, sorting, and pagination. |
| GET | /signers/{signer}/factors/{id} | Retrieve a signer factor by its handle or LUID. |
| PUT | /signers/{signer}/factors/{id} | Submit a new version of a signer factor. |
| POST | /signers/{signer}/factors/{id}/proofs | Submit a signed proof to a signer factor record. |
Access & History
| Method | Path | Description |
|---|---|---|
| POST | /signers/{id}/access/!check | Evaluate what actions a signer can perform on this signer. |
| GET | /signers/{id}/changes | Retrieve the change history of a signer by its handle or LUID. |
| GET | /signers/{id}/changes/{change} | Retrieve a change record for a signer by handle or LUID and change number. |
| POST | /signers/{signer}/factors/{id}/access/!check | Evaluate what actions a signer can perform on this factor. |
| GET | /signers/{signer}/factors/{id}/changes | Retrieve the change history of a signer factor by its handle or LUID. |
| GET | /signers/{signer}/factors/{id}/changes/{change} | Retrieve a change record for a signer factor by handle or LUID and change number. |
Related
- About Signers — what signers are and how they identify actors
- Keys and Signatures — cryptographic key pairs and signing
- About Authentication — how the ledger verifies identity
- About Circles — grouping signers into roles
Get anchor change GET
Returns a single change by its sequence number. The change includes a full record snapshot as it existed at that point.
Create signer POST
Submit a public key to register the signer's identity. Optionally include an encrypted private key — it must be encrypted client-side using a password-derived key, as the server cannot decrypt it. Storing private keys in the ledger is not recommended. A public key is sufficient for the server to verify signed requests, and keeping private keys local eliminates the risk of server-side exposure. Additional authentication factors such as OAuth client credentials can be added after creation using the signer factor endpoints. Broadcasts the `signer-created` signal. Use [effects](/ledger/reference/api/effect) to subscribe.