Manage domains

Use this page for post-genesis domain operations. For the domain model, see Domains. For launch design, see Design your domains.

Domain changes use the standard intent flow. For signing, approval, and status checks, see Manage intents and approvals, Sign intents, and Check updates.

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:

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.

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.

The UI displays the first 100 subdomains of any domain. Use List domains or Get domain details when you need API access to domain details.

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:

{
  "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:

Dry run before submitting:

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:

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

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

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.

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

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

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

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.

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.

{
  "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.

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

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.

{
  "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.

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 or Manage policies.

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.