people

client.people manages the tenant’s people. It:

• lists the tenant’s people and devices
• reviews and answers enrollment requests
• revokes devices and offboards people
• changes roles for a person or a group

list

list returns every person in the tenant.

TypeScript

list(): Promise<TenantPerson[]>;

Swift

func list() async throws -> [TenantPerson]

Kotlin

suspend fun list(): List<TenantPerson>

Returns: Every TenantPerson in the tenant.

Records: Nothing. Not a decision.

Errors: no-session, unreachable.

devices

devices returns device certificates (cards), for one person or for the whole tenant.

TypeScript

devices(person?: Person): Promise<Card[]>;

Swift

func devices(_ person: Person? = nil) async throws -> [Card]

Kotlin

suspend fun devices(person: Person? = null): List<Card>

Parameter	Type	Description
person	Person, optional	One person’s devices. When absent, every device in the tenant.

Returns: Every matching Card.

Records: Nothing. Not a decision.

Errors: no-session, unreachable.

enrollmentRequests

enrollmentRequests returns every enrollment request that waits on an approver.

TypeScript

enrollmentRequests(): Promise<EnrollmentRequestSummary[]>;

Swift

func enrollmentRequests() async throws -> [EnrollmentRequestSummary]

Kotlin

suspend fun enrollmentRequests(): List<EnrollmentRequestSummary>

Returns: Every EnrollmentRequestSummary waiting on an approver.

Records: Nothing. Not a decision.

Errors: no-session, unreachable.

reviewEnrollment

reviewEnrollment opens a request for review and computes this device’s own comparison value. It then waits for the code. An Admin never reviews their own device.

TypeScript

reviewEnrollment(requestId: string): Promise<EnrollmentReview>;

Swift

func reviewEnrollment(_ requestId: String) async throws -> EnrollmentReview

Kotlin

suspend fun reviewEnrollment(requestId: String): EnrollmentReview

Parameter	Type	Description
requestId	string	The enrollment request to review.

Returns: An EnrollmentReview. Compare the code it computes against the one the new device’s person reads out, confirm who is asking, then call approve() or reject() on it.

Records: Nothing. Not a decision.

Who may call it: The Owner or Admin role, never for their own device’s request.

Errors: no-session, unreachable, not-found.

revoke

revoke revokes a device. It needs a fresh multi-factor sign-in. The device loses all access and its sessions end at once.

TypeScript

revoke(recipientId: RecipientId, reason: RevocationReason): Promise<Decided<{}>>;

Swift

func revoke(_ recipientId: RecipientId, reason: RevocationReason) async throws -> Decided<Void>

Kotlin

suspend fun revoke(recipientId: RecipientId, reason: RevocationReason): Decided<Unit>

Parameter	Type	Description
recipientId	RecipientId	The device to revoke.
reason	RevocationReason	"lost", "stolen" or "retired".

Returns: A Decided<{}>: allow once the card is revoked everywhere.

Records: Revoke. See Audit actions.

Who may call it: Anyone in the tenant with the Revoke action, but never for the device they are calling from.

Errors: no-session, unreachable, canceled, not-found.

offboard

offboard offboards a person and revokes everything at once. It lists the key domains that only the leaver owned, for break-glass recovery.

TypeScript

offboard(person: Person): Promise<Decided<{ ownerlessDomains: Locator[] }>>;

Swift

func offboard(_ person: Person) async throws -> Decided<[Locator]>

Kotlin

suspend fun offboard(person: Person): Decided<List<Locator>>

Parameter	Type	Description
person	Person	The person leaving the tenant.

Returns: A Decided carrying ownerlessDomains: the key domains that only this person owned, now waiting on break-glass recovery. In Swift and Kotlin the allow value is the list itself.

Records: Offboard. See Audit actions.

Errors: no-session, unreachable, not-found.

changeRole

changeRole gives or removes a role. A person cannot change their own role. A change to Owner or Admin carries the granter’s signature, after a fresh multi-factor sign-in.

TypeScript

changeRole(person: Person, role: Role, change: 'give' | 'remove'): Promise<Decided<{}>>;

Swift

func changeRole(_ person: Person, role: Role, change: Change) async throws -> Decided<Void>

enum Change { case give, remove }

Kotlin

suspend fun changeRole(person: Person, role: Role, change: Change): Decided<Unit>

enum class Change { GIVE, REMOVE }

Parameter	Type	Description
person	Person	Whose role changes.
role	Role	The role given or removed.
change	"give" or "remove"	Which direction.

Returns: A Decided<{}>.

Records: Change Role. See Audit actions.

Who may call it: The Owner or Admin role, never for their own role.

Errors: no-session, unreachable, canceled, not-found.

mapGroup

mapGroup maps an identity provider group to a role, as an Owner’s standing decision. The role is never Owner or Admin.

TypeScript

mapGroup(group: Group, role: Role): Promise<Decided<{}>>;

Swift

func mapGroup(_ group: Group, role: Role) async throws -> Decided<Void>

Kotlin

suspend fun mapGroup(group: Group, role: Role): Decided<Unit>

Parameter	Type	Description
group	Group	The identity provider’s group.
role	Role	The role every member gets while mapped. Never Owner or Admin.

Returns: A Decided<{}>.

Records: One decision and one access event.

Who may call it: The Owner role.

Errors: no-session, unreachable.

unmapGroup

unmapGroup removes a group’s mapping to a role.

TypeScript

unmapGroup(group: Group): Promise<Decided<{}>>;

Swift

func unmapGroup(_ group: Group) async throws -> Decided<Void>

Kotlin

suspend fun unmapGroup(group: Group): Decided<Unit>

Parameter	Type	Description
group	Group	The mapping to remove.

Returns: A Decided<{}>.

Records: One decision and one access event.

Who may call it: The Owner role.

Errors: no-session, unreachable, not-found.

Types

RevocationReason

TypeScript

type RevocationReason = 'lost' | 'stolen' | 'retired';

Swift

enum RevocationReason { case lost, stolen, retired }

Kotlin

enum class RevocationReason { LOST, STOLEN, RETIRED }

Value	Description
lost	The device is missing.
stolen	The device was taken.
retired	The device was taken out of service in the ordinary course.

EnrollmentRequestSummary

TypeScript

interface EnrollmentRequestSummary {
  requestId: string;
  person: Person;
  replaces?: RecipientId;
  requestedAt: Date;
  lapsesAt: Date;
}

Swift

struct EnrollmentRequestSummary {
  let requestId: String
  let person: Person
  let replaces: RecipientId?
  let requestedAt: Date
  let lapsesAt: Date
}

Kotlin

data class EnrollmentRequestSummary(
  val requestId: String,
  val person: Person,
  val replaces: RecipientId?,
  val requestedAt: Instant,
  val lapsesAt: Instant,
)

Field	Type	Description
requestId	string	Identifies the request.
person	Person	Who is asking.
replaces	RecipientId, optional	The card this device replaces, when it replaces a device rather than enrolling as a new one.
requestedAt	date	When the request was made.
lapsesAt	date	When it lapses unanswered.

EnrollmentReview

TypeScript

interface EnrollmentReview {
  readonly requestId: string;
  readonly person: Person;
  readonly replaces?: RecipientId;
  readonly code?: string;
  waitForCode(): Promise<string>;
  approve(): Promise<Decided<{}>>;
  reject(): Promise<Decided<{}>>;
}

Swift

struct EnrollmentReview {
  let requestId: String
  let person: Person
  let replaces: RecipientId?
  let code: String?
  func waitForCode() async throws -> String
  func approve() async throws -> Decided<Void>
  func reject() async throws -> Decided<Void>
}

Kotlin

class EnrollmentReview(
  val requestId: String,
  val person: Person,
  val replaces: RecipientId?,
  val code: String?,
) {
  suspend fun waitForCode(): String
  suspend fun approve(): Decided<Unit>
  suspend fun reject(): Decided<Unit>
}

Field	Type	Description
requestId	string	The request being reviewed.
person	Person	Who is asking.
replaces	RecipientId, optional	The card this device replaces, where it is a replacement.
code	string, optional	The code this Client computed itself, once the new device has revealed its secret. The Seald Healthcare Cloud never supplies it.
waitForCode()	function	Resolves once code is available.
approve()	function	Approves the request. Call it only after the approver compares the code and confirms who is asking. It needs a fresh multi-factor sign-in, then signs the exact request with this device key.
reject()	function	Rejects the request, after a code mismatch or an unconfirmed caller.

TenantPerson

TypeScript

interface TenantPerson {
  person: Person;
  roles: { role: Role; through?: Group }[];
  organization: string;
  devices: Card[];
  agents: Card[];
}

Swift

struct TenantPerson {
  let person: Person
  let roles: [(role: Role, through: Group?)]
  let organization: String
  let devices: [Card]
  let agents: [Card]
}

Kotlin

data class TenantPerson(
  val person: Person,
  val roles: List<RoleGrant>,
  val organization: String,
  val devices: List<Card>,
  val agents: List<Card>,
)

data class RoleGrant(val role: Role, val through: Group?)

Field	Type	Description
person	Person	The person.
roles	list of role and optional group	Each role held, and the group it came through where mapped rather than given directly.
organization	string	The person’s organization.
devices	Card[]	This person’s own cards.
agents	Card[]	The AI agents this person delegates to.