Share

You share a key domain, not a single object. Sharing gives the person or group access to every object in the key domain, now and in the future. Access covers every device of the person, and every future member of the group. Only a domain owner can share. client.domains can also share a single record without giving access to the key domain.

Share and unshare a key domain

share takes the key domain’s root locator and a ShareTarget, either { person } or { group }. Sharing to a person gives every device they hold access, across every epoch the key domain has had. Sharing to a group is a standing decision. When a person joins the group later, an existing member device gives them access in its next session. You do nothing more.

The samples use the allowed helper from Access decisions.

TypeScript

await allowed(await client.domains.share(root, { person: alice }));
await allowed(await client.domains.share(root, { group: 'cardiology-nurses' }));

Swift

_ = try await allowed(client.domains.share(root, to: .person(alice)))
_ = try await allowed(client.domains.share(root, to: .group("cardiology-nurses")))

Kotlin

allowed(client.domains.share(root, to = ShareTarget.ToPerson(alice)))
allowed(client.domains.share(root, to = ShareTarget.ToGroup("cardiology-nurses")))

share resolves with the key domain’s new escrowVersion once the share is recorded. unshare removes access at once and starts a new epoch. The person keeps access to versions saved before the unshare, under the epoch they held. They cannot open versions saved after it.

TypeScript

await allowed(await client.domains.unshare(root, { person: alice }));

Swift

_ = try await allowed(client.domains.unshare(root, from: .person(alice)))

Kotlin

allowed(client.domains.unshare(root, from = ShareTarget.ToPerson(alice)))

Share a single record

shareRecord and unshareRecord give or remove access to one record’s versions for a person outside the key domain. That person is a record recipient, not a domain member. Access works version by version, not for the whole key domain at once. Each version adds its own cost. For ordinary sharing, share the key domain.

TypeScript

const shared = await allowed(await client.domains.shareRecord(locator, bob));
await allowed(await client.domains.unshareRecord(locator, bob));

Swift

let shared = try await allowed(client.domains.shareRecord(locator, to: bob))
_ = try await allowed(client.domains.unshareRecord(locator, from: bob))

Kotlin

val shared = allowed(client.domains.shareRecord(locator, to = bob))
allowed(client.domains.unshareRecord(locator, from = bob))

shareRecord resolves with the number of versions it added access to. The recipient shows up beside the record’s other recipients the next time you list it.

What the SDK does for you

• Verifies every device certificate (card) of a target against the trust root built into the SDK, before giving it access.
• Gives access to every device a shared person holds, not only their current one.
• Keeps a group share a standing decision. A member device gives a later joiner access. You do nothing.
• Starts a new epoch on every unshare. A removed person keeps only what they already had.

Decisions and errors you may see

Outcome or ErrorCode	When	What to do
deny	The caller is not a domain owner, or the policies otherwise refuse the share.	Show text. Only a domain owner can share a key domain. Only a domain owner or a person holding the Owner role can unshare it.
challenge	The policies require a fresh multi-factor sign-in first.	Call stepUp(), or use the allowed helper.

Next

• Owners and sub-domains for who may call share.
• List and search to see recipients on an entry.
• The trust model for how cards and shared access fit together.
• Datasets on S3 for why a share touches no object in storage.