Ripple Custody exposes a complete set of APIs to administer and operate the system programmatically. The below entities are at the core of the system:

• intents represent requests to execute an action within the system that may eventually be executed if fully approved;
• domains define segregated sets of entities (e.g., users, policies and accounts) with guaranteed isolation from each other;
• users are human or technical consumers of the service;
• policies are operational rules defining the required (multi-)approval workflow for the execution of particular intents;
• vaults are logical key stores responsible for the building and signing of outgoing transactions;
• accounts are particular sets of addresses within a vault for which balance(s) and transactions are tracked;
• transaction orders are orders to transfer digital assets or request an operation on the ledger;
• transactions are incoming or outgoing ledger transactions that have been detected on the ledger or shall be broadcast;
• transfers are the financial representation of their corresponding transactions;
• endpoints associate ledger addresses with human-readable aliases to keep track of whitelisted and blacklisted addresses;
• ledgers are accounting systems that are supported and tracked;
• tickers define the detected currencies and their respective symbols and parameters;
• events are the notification payloads generated through user actions, system signals, and ledger updates.
• requests allow to follow the progress of a user request and identify a possible failure.

Because the security of digital assets is paramount, Harmonize leverages multiple security protocols ensuring a proper management of the keys, of the signature process, of user authentication, of the application of governance policies and overall of data integrity system-wide. Notably,

• every request to mutate the system, as modelled through an intent, must be signed by all parties involved, such that an end-to-end secure link is set between the API consumer and the core of Harmonize;
• every request to mutate the system is subject to programmable policies that regulate the exact quorum of users being authorized to approve and execute the intent;
• every critical entity is protected by a data integrity protocol. Entities are versioned and stored as part of a Merkle tree whose root is signed for any mutation of the data. Any data tampering attempt at the database level or in transit is identified and fails at runtime. All such protected entites are wrapped into a data envelope and augmented with a signature field at the API level to allow a validation of the data integrity from the outside the system. This is particularly relevant to validate, for instance, the integrity of deposit addresses of a given account.

Most entity types rely on a common pattern exposing the following fields:

• id: a user-defined unique identifier (UUID); once defined, an id cannot be modified
• metadata.revision: a system-enforced revision number set to 1 for the creation of the entity, and incremented at every entity update
• metadata.description: an optional user-defined description of the entity
• metadata.createdAt: a system-enforced timestamp marking the creation time of the entity
• metadata.createdBy: a system-enforced reference to the creator of the entity
• metadata.lastModifiedAt: a system-enforced timestamp marking the last update time of the entity
• metadata.lastModifiedBy: a system-enforced reference to the last updater of the entity
• metadata.customProperties: a user-defined key-value store to attach arbitrary data to the entity, such as a correlation identifier; customProperties are part of the evaluation context of policies conditions and may be used to trigger particular approval workflows

Together, id and metadata.revision are the basis of the anti-replay model in Harmonize.

Most entities also expose a lock flag to make the entity read-only and prevent its use during runtime:

• lock: lock status of an entity, which may be Locked or Unlocked; an Unlocked entity inherits the lock of its hierarchical parent and a Locked entity (with its dependent entities) may not be used at runtime.

Locking a domain will lock all its inner entities as well as subdomains; locking a user will prevent it from submitting any request to the system or to access the service; locking a policy will ignore it entirely in the context of the policy selection; locking a vault will lock all its related accounts; locking an account will prevent the execution of transactional operations; locking an endpoint will prevent its use as a transaction order destination.

For requests returning a list of entities, pagination is enabled by default. The request may include a limit parameter to properly quantify the size of the response, a startingAfter parameter to define the anchor point, sortBy to define a possible sorting property, sortOrder to specify the direction of the sorting (resp. "ASC", "DESC") and possibly filtering criterions that may be entity-specific.

Responses are packaged within a list of items and a pointer to the next page is exposed as property nextStartingAfter.