Devices

ScaiKey provides a per-user device registry that holds long-lived asymmetric public key material. It's the identity substrate for end-to-end-encryption features — the initial driver is ScaiClip but the shape is protocol-agnostic and any ScaiLabs product that needs "encrypt something so only this specific device can open it" can consume the same registry.

Two key ideas make this different from anything else in ScaiKey:

• A device is a first-class principal with its own long-lived keypairs, separate from sessions, from MFA authenticators, and from OAuth clients. A user's laptop, phone, and browser tabs each get their own device row.
• Private keys never leave the enrolling device. The device generates both keypairs locally (Secure Enclave, TPM, Android Keystore, iOS Keychain where the OS allows) and publishes only the public halves. ScaiKey is a directory; it does no encryption itself.

Cryptographic shape#

Each device holds two public keys:

Both are exactly 32 bytes on the wire. ScaiKey validates wire format at enrolment and rotation — wrong-length, all-zeros, and known small-order Curve25519 points are rejected with a 400 INVALID_PUBLIC_KEY response identifying which algorithm and reason.

The wire format inside JSON is base64. Both url-safe (A-Za-z0-9_-) and standard (A-Za-z0-9+/) alphabets are accepted on input, with or without padding. ScaiKey emits url-safe base64 without padding on output.

Lifecycle#

1

enrol → (heartbeat, rotate, revoke)*

• Enrol (POST /me/devices) — the device generates both keypairs, publishes public halves. Fires device.registered.
• Rotate (PUT /me/devices/{id}/keys) — replace both public keys atomically. key_version bumps by one, keys_rotated_at updates. Fires device.keys.rotated. The old public keys are overwritten; ScaiKey does not maintain a history table because the client is authoritative for how to handle in-flight ciphertexts wrapped with the old key.
• Heartbeat (POST /me/devices/{id}/heartbeat) — updates last_seen. No webhook fires; heartbeats are noisy by construction.
• Revoke (DELETE /me/devices/{id} or POST /admin/users/{uid}/devices/{did}/revoke) — soft-delete. The row stays in the table so audit can reconstruct history; directory lookups filter it out. Fires device.revoked.

Revocation is soft-delete only; there is no hard-delete path. Devices retained under revoked_at are visible via include_revoked=true on the list endpoints and remain in audit history indefinitely.

Presence#

Presence is push-based. There are three heartbeat endpoints, differing in auth and shape:

• POST /me/devices/{id}/heartbeat — session-authenticated, device pushes its own liveness.
• POST /devices/heartbeat — service-authenticated, upstream reports a batch of device liveness in one call. This is the primary shape for high-fan-out gateways: one call per cadence carrying every observed device_id.
• POST /devices/{id}/heartbeat — service-authenticated single-device, for tests and low-fan-out tools.

All three update last_seen. Consumers reading device records get an online: bool field computed server-side from last_seen and a configurable staleness threshold:

1

online := now - last_seen ≤ settings.devices.online_threshold_seconds

Default threshold is 90 seconds — 3× tolerance for a 30-second heartbeat cadence. Operators can override via the SCAIKEY_DEVICES__ONLINE_THRESHOLD_SECONDS environment variable. A device that has never heartbeated (last_seen: null) reports online: false, even if it was enrolled seconds ago.

There is no server-derived presence from session activity today. If your consumer needs stronger presence guarantees than heartbeat cadence supports, subscribe to the device.* webhooks and maintain your own state.

Directory queries#

Two query shapes serve the "look up the public keys for a set of principals" pattern:

Bulk by subjects — for channel-membership dispatch. Callers list up to 100 user subjects; ScaiKey returns all their live devices in one round trip.

1

GET /tenants/{tenant_id}/devices?subjects=usr_alice,usr_bob,urn:scaikey:acme:usr:usr_carol

Subjects accept the stable usr_… ID (canonical, matches token subjects and webhook resource IDs) or the URN form urn:scaikey:{tenant_slug}:usr:{user_id} (compatibility shape for SCWP-native callers). Both resolve to the same user. Unknown or malformed subjects are surfaced in an unknown_subjects array alongside the successful data list, so a caller can distinguish "user has no devices" from "input was garbled."

Transitive by group — for team channels. Given a group, walk descendants via nested-group containment, return the union of every effective member's live devices.

1

GET /tenants/{tenant_id}/groups/{group_id}/devices

The group graph is cycle-safe and capped at 1024 groups per walk. Response includes effective_group_count so a caller can eyeball whether the traversal found what they expected.

Both queries are same-tenant-only by default. Cross-tenant lookups return 403 CROSS_TENANT_DENIED unless the caller is a live super-admin — the same guard that gates the rest of the directory namespace. If you need cross-tenant channels, a directory:read:cross_tenant scope is on the roadmap.

Webhooks#

Three events, same envelope shape as the rest of the ScaiKey event bus:

• device.registered — payload includes user_id, device_id, kem_pub, sig_pub, key_version, kind, platform.
• device.keys.rotated — user_id, device_id, kem_pub, sig_pub, key_version, keys_rotated_at.
• device.revoked — user_id, device_id, revoked_reason, revoked_at. The webhook envelope's actor_type field is user for self-revoke and admin for operator-initiated revocation — downstream consumers use this to distinguish an ordinary "lost laptop" revoke from an operator kill-switch that may want a wider rekey fan-out.

Subscribe to device.* to catch all three; the delivery worker handles wildcards.

What ScaiKey does NOT do#

• No private-key storage. The two private keys never touch ScaiKey. Hardware-backed storage is the enrolling device's concern.
• No HPKE seal / open. ScaiKey validates the wire format of public keys and stores them. All encrypt / decrypt happens on your side.
• No channel keys, content keys, or session keys. Those are the consumer's concern (ScaiClip's channel-key ratcheting, for example).
• No per-request device attestation. Devices identify to ScaiKey at enrolment via the user's session; requests stay user-authenticated. If your product needs per-request "prove you're still this device", raise it as a separate ask.
• No cascade into sessions / refresh tokens on revoke. A revoked device's public keys stop appearing in directory queries; existing user sessions and OAuth refresh tokens are not touched. If you need "kill this device across all its trust relationships", subscribe to device.revoked and take that action on your side.

What's next#

• Devices reference — endpoint schemas, error codes, exact request / response shapes.
• Federation — for identity provenance; devices are per-user regardless of how the user authenticates.