# Manage domains

Use this page for post-genesis domain operations. For the domain model, see [Domains](/products/custody/governance/domains). For launch design, see [Design your domains](/products/custody/governance/genesis/design-your-domains).

## Domain actions

| Action | UI procedure | API procedure |
|  --- | --- | --- |
| Create a domain | [Create a domain in the UI](#create-a-domain-in-the-ui) | [Create a domain with the API](#create-a-domain-with-the-api) |
| View domain details | [View domain details in the UI](#view-domain-details-in-the-ui) | [View domain details with the API](#view-domain-details-with-the-api) |
| Update domain details | [Update domain details in the UI](#update-domain-details-in-the-ui) | [Update domain details with the API](#update-domain-details-with-the-api) |
| Update domain read access | [Update domain read access in the UI](#update-domain-read-access-in-the-ui) | [Update domain read access with the API](#update-domain-read-access-with-the-api) |
| Lock and unlock a domain | [Lock or unlock a domain in the UI](#lock-or-unlock-a-domain-in-the-ui) | [Lock or unlock a domain with the API](#lock-or-unlock-a-domain-with-the-api) |
| Inject a domain | Use the API procedure. | [Inject a domain](/products/custody/governance/domains/inject-a-domain) |


## API reference and shared process

| Task | API reference |
|  --- | --- |
| Propose a domain intent | [Propose an intent](/products/custody/reference/api/openapi/intents/createintent) |
| Dry run a domain intent | [Perform a dry run](/products/custody/reference/api/openapi/intents/intentdryrun) |
| View a domain | [Get domain details](/products/custody/reference/api/openapi/domains/getdomain) |
| List domains | [List domains](/products/custody/reference/api/openapi/domains/getdomains) |
| Check known roles | [Get known user roles](/products/custody/reference/api/openapi/users/getknownuserroles) |


Domain 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 domain | `v0_CreateDomain` | Add a new governance boundary after launch. |
| Update domain details | `v0_UpdateDomain` | Change mutable details such as alias, description, or custom properties. |
| Update domain permissions | `v0_UpdateDomainPermissions` | Change read access by role. |
| Lock domain | `v0_LockDomain` | Temporarily suspend activity in a domain. |
| Unlock domain | `v0_UnlockDomain` | Re-enable a locked domain. |


## Create a domain in the UI

All environments include at least a root domain. After setup, you create new domains as subdomains of the root domain or of an existing subdomain.

1. From the domain selector, select the parent domain.
2. Go to **Domains**.
3. Click **Create a domain**.
4. Enter the domain details.
5. Review the summary.
6. Click **Submit for approval**.
7. Sign the operation with the mobile app.


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

Use these UI pages to enter the domain details:

| Page | Details |
|  --- | --- |
| General information | Domain name, optional description, custom properties, and governing strategy. Choose **Coerce descendants** to ignore policies in subdomains, or **Consider descendants** to consider policies in subdomains. If you do not choose a governing strategy, `ConsiderDescendants` applies. |
| User information | One or more users associated with the domain, including email address for an existing or new user and user role within the domain. |
| Access management | Read-only access by role for each entity type, and the roles that can administer the default policy created with the domain. |
| Summary | Details entered for review and submission. |


When you create a domain in the UI, the domain is created with a default catch-all policy. Update that policy and add more specific policies so the domain matches your governance model.

## View domain details

### View domain details in the UI

In the UI, you can view the current domain and its subdomains:

1. From the domain selector, select the top-level domain to view.
2. Go to **Domains**.
3. To view the subdomains of a domain, click the arrow next to the domain.
4. To view domain details, click the domain.


### View domain details with the API

The UI displays the first 100 subdomains of any domain. Use [List domains](/products/custody/reference/api/openapi/domains/getdomains) or [Get domain details](/products/custody/reference/api/openapi/domains/getdomain) when you need API access to domain details.

## Create a domain with the API

Create a domain by submitting a `v0_CreateDomain` intent. The payload can include initial users and policies for the new domain.

Before you create a domain, prepare:

| Prerequisite | Additional information |
|  --- | --- |
| Available roles | Call [Get known user roles](/products/custody/reference/api/openapi/users/getknownuserroles). You can also use new roles if required. |
| New IDs | Prepare a domain ID, any user IDs, any policy IDs, and an intent ID in standard UUID format. |
| Governing strategy | Choose `ConsiderDescendants`, `CoerceDescendants`, or omit the field to use the default `ConsiderDescendants` behavior. |
| Read access | Decide which roles can view domains, users, endpoints, policies, accounts, transactions, requests, and events. |



```json
{
  "payload": {
    "id": "1f1e3d9c-f2bf-4a92-a0fa-4a825e70ecb4",
    "alias": "Operations",
    "lock": "Unlocked",
    "governingStrategy": "ConsiderDescendants",
    "permissions": {
      "readAccess": {
        "domains": ["admin", "manager"],
        "users": ["admin", "manager"],
        "accounts": ["admin", "manager", "trader"],
        "transactions": ["admin", "manager", "trader"],
        "policies": ["admin"],
        "endpoints": ["admin", "manager"],
        "requests": ["admin", "manager", "trader"],
        "events": ["admin", "manager"]
      }
    },
    "description": "Operations domain",
    "customProperties": {},
    "users": [],
    "policies": [],
    "type": "v0_CreateDomain"
  }
}
```

Field notes:

| Field | Notes |
|  --- | --- |
| `id` | New domain ID in UUID format. |
| `lock` | Use `Locked` to create an inactive domain and unlock it later. |
| `governingStrategy` | `ConsiderDescendants` considers subdomain policies. `CoerceDescendants` ignores matching subdomain policies. |
| `permissions` | Role-based read access for each entity type in the domain. |
| `users` | Users to create with the domain. |
| `policies` | Policies to create with the domain. Use the field shape in [Policy reference](/products/custody/governance/policies/reference). |
| `type` | `v0_CreateDomain`. |


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-domain-intent.json
```

Submit the signed intent:


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

## Update domain details

Use `v0_UpdateDomain` to update mutable domain details such as alias, description, and custom properties.

### Update domain details in the UI

You can update the alias and description of a subdomain from the root domain:

1. Select the root domain from the domain selector.
2. Go to **Domains**.
3. In the domain hierarchy, click the domain to update.
4. Click **Edit information**.
5. Update **Name** or **Description**.
6. Click **Submit for approval**.
7. Sign the operation with the mobile app.


### Update domain details with the API

Submit an update intent with the `targetDomainId` set to the domain to update. The update payload uses the current domain reference:


```json
{
  "payload": {
    "reference": {
      "id": "1f1e3d9c-f2bf-4a92-a0fa-4a825e70ecb4",
      "revision": 2
    },
    "alias": "Operations",
    "description": "Updated operations domain description",
    "customProperties": {},
    "type": "v0_UpdateDomain"
  }
}
```

## Update domain read access

Use `v0_UpdateDomainPermissions` to update read access. Use `v0_UpdateDomain` for mutable domain details such as alias, description, and custom properties.

### Update domain read access in the UI

1. Select the domain, or another domain above it in the same hierarchy, from the domain selector.
2. Go to **Domains**.
3. In the domain hierarchy, click the domain to update.
4. Click **Edit read permissions**.
5. In **Read permissions**, add or remove user roles.
6. Select the entities each role can view.
7. Click **Submit for approval**.
8. Sign the operation with the mobile app.


### Update domain read access with the API

Domain permission updates can be submitted:

- By a user in a parent domain, through an intent submitted to the parent domain.
- By a user in a parent domain, through an intent submitted to a subdomain.
- By a user in a subdomain, through an intent submitted to the subdomain.



```json
{
  "payload": {
    "reference": {
      "id": "1f1e3d9c-f2bf-4a92-a0fa-4a825e70ecb4",
      "revision": 2
    },
    "permissions": {
      "readAccess": {
        "domains": ["admin", "auditor"],
        "users": ["admin", "auditor"],
        "accounts": ["admin", "auditor", "compliance"],
        "transactions": ["admin", "auditor", "compliance"],
        "policies": ["admin", "auditor"],
        "endpoints": ["admin"],
        "requests": ["admin", "auditor", "compliance"],
        "events": ["admin", "auditor", "compliance"]
      }
    },
    "type": "v0_UpdateDomainPermissions"
  }
}
```

Before updating read access, confirm that approvers and auditors can still see the records they need.

## Lock and unlock a domain

Use lock operations for incident response, investigations, temporary suspension, or decommissioning.

### Lock or unlock a domain in the UI

1. Select the domain, or another domain above it in the same hierarchy, from the domain selector.
2. Go to **Domains**.
3. In the domain hierarchy, click the domain to lock or unlock.
4. If the domain is unlocked, click **Lock**. If it is locked, click **Unlock**.
5. Sign the operation with the mobile app.


### Lock or unlock a domain with the API


```json
{
  "payload": {
    "reference": {
      "id": "1f1e3d9c-f2bf-4a92-a0fa-4a825e70ecb4",
      "revision": 2
    },
    "type": "v0_LockDomain"
  }
}
```

Use `v0_UnlockDomain` to re-enable the domain. When a domain is locked, users cannot submit intents in that domain or any of its subdomains.

## Add or update entities in a domain

To add or update entities in a domain, select the target domain from the domain selector and follow the relevant governance procedure, such as [Manage users and roles](/products/custody/governance/users/manage-users-and-roles) or [Manage policies](/products/custody/governance/policies/reference).

## Operational checklist

Before submitting a domain intent:

- Confirm the parent domain and governing strategy.
- Confirm read access for operators, approvers, compliance, and auditors.
- Confirm the policy that will govern the domain intent.
- Confirm approvers can satisfy quorum without relying on users being created by the same intent.
- Dry run the payload.
- Verify the executed change by viewing the domain.


For domain fields, see [Domain reference](/products/custody/governance/domains/reference).