Enroll a device

A device needs a device certificate (card) before it can do anything in a tenant. The tenant’s identity authority signs the card. Your application starts an enrollment, shows the person a six-digit code and waits. An approver’s device confirms the code and signs the approval. The SDK then verifies the card offline and returns a Client.

Ask for a card

Call enroll with the hostname the person entered and the tenant to join. If this device replaces a lost or retired one, add the RecipientId it replaces. Leave replaces out for a brand new device.

const enrollment = await sealdhealthcare.enroll({ hostname: 'records.example-health.com', tenantId });

let enrollment = try await sealdhealthcare.enroll(EnrollRequest(hostname: "records.example-health.com", tenantId: tenantId))

val enrollment = sealdhealthcare.enroll(EnrollRequest(hostname = "records.example-health.com", tenantId = tenantId))

Enrollment starts in state pending. It moves through the states below as the approver’s device does its part. Watch on('change') and show the code when it appears. Call wait() to get a Client once the SDK holds and has verified the card.

`EnrollmentState`	What is happening
`pending`	The request was sent. No approver has opened it yet.
`opened`	An approver’s device opened the request.
`revealed`	This device revealed its secret. The code can now be read out.
`approved`	The approver confirmed the code and signed.
`enrolled`	The SDK holds the card and verified it offline. `wait()` resolves with the `Client`.
`rejected`	The approver declined, or confirmed the wrong caller. `wait()` rejects with `enrollment-rejected`.
`lapsed`	Nobody approved before the request’s `lapsesAt`. `wait()` rejects with `enrollment-lapsed`.

enrollment.on('change', () => enrollment.code && showCode(enrollment.code));
const client = await enrollment.wait(); // rejects with enrollment-rejected or enrollment-lapsed

for await _ in enrollment.on(.change) where enrollment.code != nil { showCode(enrollment.code!) }
let client = try await enrollment.wait()

enrollment.on(EnrollmentEvent.CHANGE).collect { enrollment.code?.let { showCode(it) } }
val client = enrollment.wait()

The person reads the code out loud, or over the phone, to whoever is approving. If they change their mind before an approver signs, call cancel() to withdraw the request and discard the key it generated.

await enrollment.cancel();

try await enrollment.cancel()

enrollment.cancel()

Resume after a restart

If the application restarts while an enrollment is outstanding, do not start a second request. Call resumeEnrollment with the requestId you kept. Keep watching the same Enrollment.

const enrollment = await sealdhealthcare.resumeEnrollment(requestId);

let enrollment = try await sealdhealthcare.resumeEnrollment(requestId)

val enrollment = sealdhealthcare.resumeEnrollment(requestId)

What this device already holds

enrollments() returns one EnrollmentSummary for each tenant this device is enrolled in. Each summary carries the hostname it enrolled against and the card’s last known cardState. Use it to build a tenant picker, or to decide whether to enroll again or connect.

const summaries = await sealdhealthcare.enrollments();
const client = await sealdhealthcare.connect(tenantId); // unlocks the device key, with no session yet

let summaries = try await sealdhealthcare.enrollments()
let client = try await sealdhealthcare.connect(tenantId)

val summaries = sealdhealthcare.enrollments()
val client = sealdhealthcare.connect(tenantId)

To remove an enrollment from this device, call forget. The card itself stays active in the tenant until an Owner or Admin revokes it there. forget only removes this device’s local copy of the key.

await sealdhealthcare.forget(tenantId);

try await sealdhealthcare.forget(tenantId)

sealdhealthcare.forget(tenantId)

What the SDK does for you

Generates the device key and holds it nowhere but on this device.
Reveals the secret behind the code only once an approver’s device has opened the request.
Verifies the signed card offline, against the trust root built into the SDK, before it reports the device as enrolled.
Keeps a request alive across a restart. resumeEnrollment never starts a duplicate.

Decisions and errors you may see

Outcome or `ErrorCode`	When	What to do
`enrollment-rejected`	An approver declined the request, or did not recognize the caller.	Tell the person to start a new enrollment and confirm who they are asking.
`enrollment-lapsed`	Nobody approved before `lapsesAt`.	Start a fresh `enroll` call.

Approve an enrollment from the reviewing device.
Found a tenant when there is no existing device to approve yet.
Sessions to sign in once a device is enrolled.
Restore a lost device when replaces is what you need.