# Manage vaults

Use this page for post-installation vault operations. For the conceptual model, see [Vaults](/products/custody/identity-and-access/vault-management). A vault is an external component that securely manages blockchain transaction signing. All external vaults must be registered in Ripple Custody before accounts can use them.

A vault is not tied to a domain, so accounts in different domains can use the same vault. Vault registration and vault updates are performed from the root domain.

For the trust model, see [Trusted vs untrusted components](/products/custody/overview/security/data-integrity-and-audit-trail#trusted-vs-untrusted-components). For key strategy and backup implications, see [Vaults](/products/custody/identity-and-access/vault-management#key-strategies-and-backup-implications).

## Vault actions

| Action | UI procedure | API procedure |
|  --- | --- | --- |
| Register a vault | [Register a vault in the UI](#register-a-vault-in-the-ui) | [Register a vault with the API](#register-a-vault-with-the-api) |
| View vault details | [View vault details](#view-vault-details) | [View vault details](#view-vault-details) |
| Update a vault | [Update a vault](#update-a-vault) | [Update a vault](#update-a-vault) |
| Lock or unlock a vault | Use the API procedure. | [Lock or unlock a vault](#lock-or-unlock-a-vault) |
| Process cold vault operations | [Process cold vault operations in the UI](/products/custody/identity-and-access/vault-management/cold-vault-setup-ui) | [Process cold vault operations with the API](/products/custody/identity-and-access/vault-management/cold-vault-setup-api) |


## API reference and shared process

| Task | API reference |
|  --- | --- |
| Propose a vault intent | [Propose an intent](/products/custody/reference/api/openapi/intents/createintent) |
| Dry run a vault intent | [Perform a dry run](/products/custody/reference/api/openapi/intents/intentdryrun) |
| List vaults | [List vaults](/products/custody/reference/api/openapi/vaults/getvaults) |
| Get vault details | [Get vault details](/products/custody/reference/api/openapi/vaults/getvault) |
| Export prepared cold vault operations | [Export prepared operations](/products/custody/reference/api/openapi/vaults/paths/~1v1~1vaults~1{vaultid}~1operations~1prepared/get) |
| Import signed cold vault operations | [Import signed operations](/products/custody/reference/api/openapi/vaults/paths/~1v1~1vaults~1operations~1signed/post) |


Vault changes use the standard intent flow. For signing, approval, and status checks, see [Manage intents and approvals](/products/custody/governance/intents/manage-intents-and-approvals), [Sign intents](/products/custody/identity-and-access/authentication/authenticate-api-requests#signing-intents-state-mutation-operations), and [Check updates](/products/custody/governance/intents/manage-intents-and-approvals#check-state).

## Common operations

| Operation | Intent type | Use when |
|  --- | --- | --- |
| Create vault | `v0_CreateVault` | Register a deployed vault component. |
| Update vault | `v0_UpdateVault` | Change mutable vault details such as alias, description, custom properties, or parameters. |
| Lock vault | `v0_LockVault` | Prevent transaction orders related to the vault from executing. |
| Unlock vault | `v0_UnlockVault` | Re-enable a locked vault. |


## Register a vault in the UI

Whenever you deploy a new vault, register it by creating a corresponding vault entity. You can only register vaults in the root domain. You can then use the vault to execute transactions in any domain.

Before you register the vault, collect the vault's public key and ID from the vault logs, as described in [First-time installation](/products/custody/deployment/install/first-time-installation).

At registration, set the key management system (KMS) type to either `HSM` or `MPC` so the system can use the correct vault behavior. For more information about MPC key management, contact your Ripple liaison.

To register a vault:

1. Select the root domain from the **Domain** drop-down menu.
2. Go to **Administration > Vaults**.
3. Click **Create a vault**.
4. Enter the vault name, vault ID in UUID format, and KMS type.
5. Enter or upload the vault public key.
6. Enter any required custom properties.
7. Click **Submit for Approval** and [sign the operation with the app](/products/custody/identity-and-access/authentication/ui-authentication#sign-ui-operations).


The vault is created after the intent is approved and executed.

## Register a vault with the API

Create a vault by submitting a `v0_CreateVault` intent.

Before you register a vault, prepare:

| Prerequisite | Additional information |
|  --- | --- |
| Vault public key and ID | Retrieve these values from the vault logs. See [First-time installation](/products/custody/deployment/install/first-time-installation). |
| Root domain context | Vaults are created from the root domain. To find domains you belong to, see [View users and roles](/products/custody/governance/users/manage-users-and-roles#view-users-and-roles-with-the-api). |
| New intent ID | Prepare an intent ID in standard UUID format. |
| KMS type | Use `HSM` or `MPC`. If `parameters.type` is not provided, `HSM` is used. |



```json
{
  "payload": {
    "id": "92f6c08d-10c9-4cbb-8e86-ec8275eda0ee",
    "alias": "vault-hot",
    "parameters": {
      "type": "HSM"
    },
    "publicKey": "MCowBQYDK2VwAyEAIX4sz/23SbbAPWBn03zpd634Xj2uwT8Y/F7iH4XY4Ig=",
    "lock": "Unlocked",
    "description": "Hot vault",
    "customProperties": {},
    "type": "v0_CreateVault"
  }
}
```

Field notes:

| Field | Notes |
|  --- | --- |
| `id` | UUID of the vault, from the vault logs. |
| `alias` | User-facing vault name. |
| `parameters.type` | KMS type: `HSM` or `MPC`. |
| `parameters.backupEncryptionKey` | For an `MPC` vault, an encryption key used by the MPC backup workflow. See [MPC-backed vaults](/products/custody/operations-and-maintenance/backup-and-restore#mpc-backed-vaults). |
| `publicKey` | Public key of the vault, from the vault logs. |
| `lock` | Use `Locked` to create an inactive vault and unlock it later with `v0_UnlockVault`. |
| `customProperties` | Optional string metadata. |
| `type` | `v0_CreateVault`. |


Dry run before submitting:


```sh
curl -X POST "${CUSTODY_API_URL}/v1/intents/dry-run" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @create-vault-intent.json
```

After the vault creation intent is approved and executed, Ripple Custody returns a `supportedDerivations` list in the `data` object. Use this information when you [create an account](/products/custody/accounts-and-assets/accounts/manage-accounts-api#create-an-account-with-the-api).

## View vault details

View vault details before creating accounts, confirming cold vault processing status, or checking the supported derivations exposed by the vault.

In the UI:

1. Go to **Administration > Vaults**.
2. Click the vault to view its details.


The UI shows general vault details, such as the vault ID, public key, and key derivations. For cold vaults, the UI also shows pending operations. For more information, see [Process cold vault operations in the UI](/products/custody/identity-and-access/vault-management/cold-vault-setup-ui).

With the API, call [List vaults](/products/custody/reference/api/openapi/vaults/getvaults) to find vaults or [Get vault details](/products/custody/reference/api/openapi/vaults/getvault) to retrieve a specific vault:


```http
GET /v1/vaults/{vaultId}
Authorization: Bearer <your_jwt_token>
```

## Update a vault

Use `v0_UpdateVault` to change mutable vault details. You can only update a vault from the root domain.

In the UI:

1. Select the root domain from the **Domain** drop-down menu.
2. Go to **Administration > Vaults**.
3. At the end of the vault row, click the contextual menu and select **Edit**.
4. Update the vault name, description, or custom properties.
5. Click **Submit for Approval** and [sign the operation with the app](/products/custody/identity-and-access/authentication/ui-authentication#sign-ui-operations).


With the API, submit an update intent with the current vault reference:


```json
{
  "payload": {
    "reference": {
      "id": "92f6c08d-10c9-4cbb-8e86-ec8275eda0ee",
      "revision": 2
    },
    "alias": "vault-hot",
    "parameters": {
      "type": "HSM"
    },
    "description": "Updated hot vault description",
    "customProperties": {},
    "type": "v0_UpdateVault"
  }
}
```

Field notes:

| Field | Notes |
|  --- | --- |
| `reference` | Current vault ID and revision. |
| `alias` | Updated user-facing vault name. |
| `parameters` | KMS parameters for the vault. |
| `description` | Optional updated description. |
| `customProperties` | Optional string metadata. |
| `type` | `v0_UpdateVault`. |


The vault is updated after the intent is approved and executed.

## Lock or unlock a vault

Lock a vault when transaction orders related to that vault should not execute. Unlock the vault only after the operational reason for the lock is resolved.

Submit a `v0_LockVault` intent with the current vault reference:


```json
{
  "payload": {
    "reference": {
      "id": "92f6c08d-10c9-4cbb-8e86-ec8275eda0ee",
      "revision": 2
    },
    "type": "v0_LockVault"
  }
}
```

Use `v0_UnlockVault` with the same reference shape to re-enable the vault.

## Operational checklist

Before submitting a vault-management intent:

- Confirm the vault ID and public key from the deployed vault logs.
- Confirm the KMS type and any backup or wrapping-key-rotation requirements.
- Confirm that the intent is submitted from the root domain.
- Confirm the policy that will govern the vault intent.
- Dry run the payload.
- Verify the executed change by viewing the vault details.