Domain
A domain defines a namespace for isolating records within a ledger. Each domain has its own scope for access rules, and records in child domains inherit access rules from their ancestors.
Domain enforcement activates after the first domain is created. Before that, all records exist in the root domain and handles are not constrained. Once active, new records must belong to an existing domain.
A record's domain can be assigned in two ways: implicitly from the record handle (e.g., account:1001@bank.com resolves to domain bank.com) or explicitly through the custom.domain field in a proof. When both are present, the proof value takes precedence. Domains cannot be changed after a record is created.
Domains support hierarchy — a child domain references a parent via its domain field, and access rules cascade from parent to child. Records created before domain enforcement remain in the root domain and are not automatically migrated.
Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /domains | Register a new namespace for data separation in the ledger. |
| GET | /domains | Query domains with filtering, sorting, and pagination. |
| GET | /domains/{id} | Retrieve a domain by its handle or LUID. |
| PUT | /domains/{id} | Submit a new version of a domain. |
| POST | /domains/{id}/proofs | Submit a signed proof to a domain record. |
Access & History
| Method | Path | Description |
|---|---|---|
| POST | /domains/{id}/access/!check | Evaluate what actions a signer can perform on this domain. |
| GET | /domains/{id}/changes | Retrieve the change history of a domain by its handle or LUID. |
| GET | /domains/{id}/changes/{change} | Retrieve a change record for a domain by handle or LUID and change number. |
Related
- About Domains — how domains organize and isolate ledger records
- About Authorization — how domains interact with access control
Get circle change GET
Returns a single change by its sequence number. The change includes a full record snapshot as it existed at that point.
Create domain POST
Domain enforcement activates after the first domain is created on a ledger. Once active, only existing domain handles are accepted when creating new records. This transition is permanent. To create a subdomain, set the `domain` field to the parent domain's handle. Access rules defined on parent domains are inherited by all descendants. Broadcasts the `domain-created` signal. Use [effects](/ledger/reference/api/effect) to subscribe.