Owners and sub-domains

Every key domain needs at least one domain owner with an enrolled device. Only a domain owner can give anyone else access to the key domain. Use client.domains to:

add domain owners
step down as a domain owner
inspect who can see a key domain
split part of a key domain into a sub-domain of its own

Add and remove domain owners

makeOwner promotes an existing member of the key domain to domain owner. giveUpOwnership lets a domain owner step down. It works only while another domain owner with a device remains. A key domain always keeps at least one.

The samples use the allowed helper from Access decisions.

await allowed(await client.domains.makeOwner(root, bob));
await allowed(await client.domains.giveUpOwnership(root)); // refused if bob is the last domain owner

try await allowed(client.domains.makeOwner(root, person: bob))
try await allowed(client.domains.giveUpOwnership(root))

allowed(client.domains.makeOwner(root, person = bob))
allowed(client.domains.giveUpOwnership(root))

Inspect membership

members returns a Membership. It carries:

the key domain’s root and dataset
the list of owners
every member, each with the through groups that brought them in, if any
the groups with a standing share
every recordRecipients entry: a record and the person it was shared to individually
the current epoch and the escrowVersion

const membership = await client.domains.members(root);
renderMembers(membership.owners, membership.members, membership.groups, membership.recordRecipients);

let membership = try await client.domains.members(root)
renderMembers(membership.owners, membership.members, membership.groups, membership.recordRecipients)

val membership = client.domains.members(root)
renderMembers(membership.owners, membership.members, membership.groups, membership.recordRecipients)

Split off a sub-domain

domains.create turns an empty folder below a dataset’s root into a key domain of its own. It generates a fresh domain key when you create a sub-domain, and makes it recoverable by break-glass recovery. The sub-domain has its own domain owners, independent of the enclosing key domain. Call it on an empty folder, as a domain owner of the enclosing key domain. The caller becomes the sub-domain’s first domain owner. Pass initial members to share it with people or groups at the same time.

const { root: subRoot } = await allowed(
  await client.domains.create(folder, { members: [{ group: 'oncology' }] }),
) ?? {};

let subRoot = try await allowed(client.domains.create(folder, members: [.group("oncology")]))

val subRoot = allowed(client.domains.create(folder, members = listOf(ShareTarget.ToGroup("oncology"))))

What the SDK does for you

Refuses to leave a key domain without a domain owner who holds a device.
Generates a fresh domain key when you create a sub-domain, and makes it recoverable by break-glass recovery.
Verifies every domain owner’s device certificate (card) against the trust root built into the SDK, before letting them share.
Gives any members named at creation access when it creates the sub-domain.

Decisions and errors you may see

Outcome or `ErrorCode`	When	What to do
`deny` on `giveUpOwnership`	The caller is the last domain owner with a device.	Make another member a domain owner first.
`deny` on `create`	The folder is not empty, or the caller is not a domain owner of the enclosing key domain.	Choose an empty folder, or ask a domain owner to create it.
`challenge`	The policies require a fresh multi-factor sign-in first.	Call `stepUp()`, or use the `allowed` helper.

Share for sharing an existing key domain with a person or group.
Delete and restore for what only a domain owner may do there.
Break-glass recovery for a key domain that already lost every domain owner’s device.
Datasets on S3 for how a sub-domain’s storage prefix works.