Devices

Settings > Devices: this device's enrollment, the account's devices, Recent Access, and the enroll and approval sheets.

Cua Spaces app export

These APIs are part of the Cua Spaces app export for building Spaces UIs. They are source-available under FSL-1.1-MIT and ship for Swift only (import CuaSpacesFFI); the Rust tab shows the cua-spaces-ffi crate they come from. The open source SDK packages for Python, TypeScript and Kotlin do not include them.

app_devices_view derives the Devices page from app_devices_input (a Devices.snapshot): this device's enrollment, the account's devices with their buttons, approval prompts that ask for presence, and Recent Access in words. app_enroll_reduce / app_enroll_view drive the enroll sheet (sign in again, or a one-time code approved elsewhere); app_approve_reduce / app_approve_view drive the approval sheet, whose request goes to Devices.approve after Touch ID or the login password; app_confirm_presence asks for that confirmation with the system's own prompt (Touch ID or the login password on macOS, Windows Hello, polkit on Linux). app_machine_access_notice says why a device that is signed in but not enrolled cannot open the account's machines, for their greyed-out Connect.

`AppAuditInput` record#

Field	Type	Description
`ts`	`u64`	Unix seconds.
`kind`	`String`	Kind.
`device`	`Option<String>`	Acting device.
`machine`	`Option<String>`	Machine id.
`subject`	`Option<String>`	Other party.
`detail`	`Option<String>`	Detail.

`AppActivityRow` record#

Field	Type	Description
`ts`	`u64`	Unix seconds.
`text`	`String`	The line.
`notable`	`bool`	Access by another account or an unenrolled device.

`AppBannerTone` enum#

.info
.warning
.critical

Variant	Description
`Info`	Informational.
`Warning`	Needs the user soon.
`Critical`	Blocks relay access now.

`AppThisDevice` record#

Field	Type	Description
`kind`	`AppEnrollmentKind`	State.
`title`	`String`	"Enrolled until", "Grace ends", "Needs enrollment", ...
`at`	`Option<u64>`	The date after the title (Unix seconds); the shell formats it.
`name`	`Option<String>`	The device's name, once registered.
`action_label` / `actionLabel`	`Option<String>`	"Enroll…" when this device needs it.

`AppEnrollmentKind` enum#

.enrolled
.grace
.needsEnrollment
.waiting
.due
.revoked

Variant	Description
`Enrolled`	Enrolled: the relay lets it reach the account's machines.
`Grace`	Not enrolled, still let through until the grace period ends.
`NeedsEnrollment`	Not enrolled, and the relay refuses it.
`Waiting`	Registered, waiting for approval from an enrolled device.
`Due`	Enrollment ran out: one approval re-verifies it.
`Revoked`	Revoked.

`AppApprovalPrompt` record#

Field	Type	Description
`device_id` / `deviceId`	`String`	Device id to approve.
`text`	`String`	The question.
`requires_presence` / `requiresPresence`	`bool`	Ask for Touch ID / the login password before approving.
`name`	`String`	The device's name.
`expired`	`bool`	Re-verification of a device whose enrollment ran out (no code).
`notify_title` / `notifyTitle`	`String`	The system notification's title.
`notify_body` / `notifyBody`	`String`	The system notification's body.

`AppMachineInput` record#

Field	Type	Description
`id`	`String`	Machine id.
`name`	`String`	Display name.
`confirmed`	`bool`	Registered with an enrolled device's proof, or confirmed since (S5). `true` from a relay that predates the check.

`AppUnconfirmedMachine` record#

Field	Type	Description
`id`	`String`	Machine id (the native side's `confirm_machine` call takes this).
`title`	`String`	Display name, or the id when it has none yet.
`confirm`	`AppDeviceConfirm`	Asked before confirming (both shells show it as a native alert).

`app_machine_access_notice`#

Why this device cannot open the account's machines for its enrollment kind (None while it can). pending_code is the code it shows while it waits for approval.

func appMachineAccessNotice(kind: AppEnrollmentKind, pendingCode: String?) -> AppMachineAccessNotice?

Parameter	Type	Default
`kind`	`AppEnrollmentKind`	required
`pending_code`	`Option<String>`	required

Returns Option<AppMachineAccessNotice>

`AppMachineAccessNotice` record#

Returned by app_machine_access_notice.

Field	Type	Description
`kind`	`AppEnrollmentKind`	This device's enrollment.
`status`	`String`	The machine's Status: "Not enrolled", "Waiting for approval", ...
`text`	`String`	The line above the disabled Connect.
`action_label` / `actionLabel`	`String`	The action's label; it opens the enroll sheet.

`AppApproveRequest` record#

Field	Type	Default	Description
`code`	`Option<String>`		The code (a new device).
`device_id` / `deviceId`	`Option<String>`		The device id (re-verification).

`AppApproveSheetState` record#

Returned by app_approve_open, app_approve_reduce.

Field	Type	Description
`device_id` / `deviceId`	`String`	The device to approve.
`name`	`String`	Its name.
`expired`	`bool`	Re-verification (no code) rather than a new device.
`code`	`String`	The code as typed.
`busy`	`bool`	The approval runs (presence, then the relay).
`error`	`Option<String>`	The last failure.
`code_expired` / `codeExpired`	`bool`	The last code the relay saw expired: offers approving the waiting device of this name by id instead (see `code_expired_fallback`). Typing a new code clears it.

`AppApproveSheetView` record#

Returned by app_approve_view.

Field	Type	Description
`title`	`String`	Title.
`message`	`String`	What approving does.
`needs_code` / `needsCode`	`bool`	A code field shows.
`code_label` / `codeLabel`	`String`	The code field's label.
`code_placeholder` / `codePlaceholder`	`String`	Its placeholder.
`code`	`String`	The code, normalized (`K7QX-M2RP`).
`can_approve` / `canApprove`	`bool`	Approve is enabled.
`approve_label` / `approveLabel`	`String`	Approve.
`deny_label` / `denyLabel`	`String`	Deny (a new device; revokes it) or Not Now (re-verification).
`deny_revokes` / `denyRevokes`	`bool`	Deny revokes the device (one click, no confirmation).
`presence_reason` / `presenceReason`	`String`	The reason the presence prompt shows.
`busy`	`bool`	Working.
`error`	`Option<String>`	A failure.
`request`	`Option<AppApproveRequest>`	What to send once presence is confirmed (`None` until ready).

`AppDeviceBanner` record#

Field	Type	Description
`tone`	`AppBannerTone`	Tone.
`text`	`String`	Text.
`action`	`Option<AppDeviceAction>`	Button, if any.
`action_label` / `actionLabel`	`Option<String>`	The button's label.

`AppDeviceConfirm` record#

Field	Type	Description
`title`	`String`	The question.
`message`	`String`	What happens.
`confirm_label` / `confirmLabel`	`String`	The confirming button.
`cancel_label` / `cancelLabel`	`String`	The other button.

`AppDeviceInput` record#

Field	Type	Description
`id`	`String`	`dev_…`.
`name`	`String`	Display name.
`state`	`String`	`pending`, `enrolled`, `expired` or `revoked`.
`enrolled_until` / `enrolledUntil`	`Option<u64>`	Re-verification due at (Unix seconds).
`last_seen` / `lastSeen`	`Option<u64>`	Last session (Unix seconds).
`current`	`bool`	This device.
`platform`	`Option<String>`	Operating system the device reported (`macos`, `windows`, `linux`).

`AppDeviceRow` record#

Field	Type	Description
`id`	`String`	Device id.
`title`	`String`	Name (`(this device)` suffix for the current one).
`subtitle`	`String`	State in words.
`actions`	`Vec<AppDeviceAction>`	Buttons.
`name`	`String`	The name as stored (Rename starts from it).
`platform`	`String`	Operating system in words (`macOS`), empty when unknown.
`detail`	`String`	Platform and state on one line.
`last_seen` / `lastSeen`	`Option<u64>`	Last session (Unix seconds); the shell says it relative to now.
`current`	`bool`	This device.
`revoke_confirm` / `revokeConfirm`	`Option<AppDeviceConfirm>`	Asked before Revoke.

`AppDevicesInput` record#

Returned by app_devices_input, app_devices_input_from_json.

Field	Type	Description
`devices`	`Vec<AppDeviceInput>`	The account's devices.
`audit`	`Vec<AppAuditInput>`	The account's audit events, newest last.
`local_device_id` / `localDeviceId`	`Option<String>`	This device's id when it has a key (it may not be registered yet).
`pending_code` / `pendingCode`	`Option<String>`	The one-time code this device shows while it waits for approval.
`enforce_after` / `enforceAfter`	`Option<u64>`	When the relay stops letting unenrolled devices through.
`machine_names` / `machineNames`	`HashMap<String, String>`	Machine ids to display names.
`machines`	`Vec<AppMachineInput>`	The account's relay machines, for the "New machine" confirm badge (S5). Empty on a relay that predates it, or when this device cannot list them, same as `machine_names`.

`AppDevicesLabels` record#

Field	Type	Description
`title`	`String`	Page title.
`this_device` / `thisDevice`	`String`	This device's section.
`devices`	`String`	The account's devices.
`recent`	`String`	The access log's section.
`recent_empty` / `recentEmpty`	`String`	When the access log is empty.
`last_seen` / `lastSeen`	`String`	"Last seen" before a relative time.
`approve`	`String`	Approve button (the row's, and the sheet's for a new device).
`deny`	`String`	The row's Deny: revokes a still-pending device in one click, or (a device due for re-verification) only dismisses it, like the sheet's Deny and Not Now.
`rename`	`String`	Rename button.
`revoke`	`String`	Revoke button.
`rename_title` / `renameTitle`	`String`	The rename prompt's title.
`rename_confirm` / `renameConfirm`	`String`	The rename prompt's confirming button.
`cancel`	`String`	Cancel.
`signed_out` / `signedOut`	`String`	Shown instead of the page while signed out.
`new_machines` / `newMachines`	`String`	The unconfirmed-machines section's heading.
`confirm_machine` / `confirmMachine`	`String`	Confirm button on a new machine.

`AppDevicesView` record#

Returned by app_devices_view.

Field	Type	Description
`banner`	`Option<AppDeviceBanner>`	Banner, if something needs the user.
`enrolled`	`bool`	This device is enrolled (relay machines are reachable).
`rows`	`Vec<AppDeviceRow>`	Device rows, this device first.
`approvals`	`Vec<AppApprovalPrompt>`	Devices this device can approve.
`activity`	`Vec<AppActivityRow>`	Access log, newest first.
`this_device` / `thisDevice`	`AppThisDevice`	This device's enrollment.
`recent`	`Vec<AppActivityRow>`	"Recent access": which device (or account) opened which machine, newest first, at most `RECENT_ACCESS_LIMIT`.
`unconfirmed_machines` / `unconfirmedMachines`	`Vec<AppUnconfirmedMachine>`	Machines registered without an enrolled device's proof, still waiting to be confirmed (S5); empty most of the time.
`labels`	`AppDevicesLabels`	Words.

`AppEnrollOption` record#

Field	Type	Description
`method`	`AppEnrollMethod`	Method.
`title`	`String`	Title.
`detail`	`String`	One line under it.

`AppEnrollState` record#

Returned by app_enroll_initial, app_enroll_reduce, app_enroll_state_from_json.

Field	Type	Description
`phase`	`AppEnrollPhase`	Phase.
`method`	`Option<AppEnrollMethod>`	The chosen method.
`code`	`Option<String>`	The one-time code, while waiting.
`error`	`Option<String>`	The last failure.

`AppEnrollView` record#

Returned by app_enroll_view.

Field	Type	Description
`title`	`String`	Title.
`lede`	`String`	One line under the title.
`options`	`Vec<AppEnrollOption>`	The methods (while choosing).
`code`	`Option<String>`	The one-time code (while waiting).
`code_help` / `codeHelp`	`Option<String>`	How to use the code.
`status`	`Option<String>`	What is happening now.
`error`	`Option<String>`	A failure.
`busy`	`bool`	Working (a spinner).
`done`	`bool`	Enrolled.
`back_label` / `backLabel`	`Option<String>`	Back (after a failure).
`close_label` / `closeLabel`	`String`	Cancel, or Done once enrolled.

`AppApproveSheetAction` enum#

.setCode(code: String)
.submit
.failed(error: String)

Variant	Description
`SetCode`	The code field changed. Fields: `code: String`
`Submit`	Approve was pressed (the shell asks for presence, then the relay).
`Failed`	Presence or the relay refused. Fields: `error: String`

`AppDeviceAction` enum#

.enroll
.approve
.rename
.revoke

Variant	Description
`Enroll`	Enroll this device (the enroll sheet).
`Approve`	Approve another device (after presence).
`Rename`	Rename a device.
`Revoke`	Revoke a device (after its confirmation).

`AppEnrollAction` enum#

.choose(method: AppEnrollMethod)
.signedIn
.registered(enrolled: Bool, code: String?)
.approved
.failed(error: String)
.back

Variant	Description
`Choose`	A method was chosen. Fields: `method: AppEnrollMethod`
`SignedIn`	The interactive sign-in finished.
`Registered`	The relay registered this device. Fields: `enrolled: bool`, `code: Option<String>`
`Approved`	An enrolled device approved this one.
`Failed`	A step failed. Fields: `error: String`
`Back`	Back to the choice.

`AppEnrollMethod` enum#

.signIn
.approve

Variant	Description
`SignIn`	A fresh interactive sign-in (enrolls this device at once).
`Approve`	A one-time code approved from an enrolled device.

`AppEnrollPhase` enum#

.choose
.signingIn
.registering
.waiting
.enrolled
.failed

Variant	Description
`Choose`	Choosing a method.
`SigningIn`	The shell runs an interactive sign-in.
`Registering`	The shell registers this device with the relay.
`Waiting`	The code shows; the shell polls until an enrolled device approves.
`Enrolled`	Enrolled.
`Failed`	Something failed; Back returns to the choice.

`app_approve_open`#

Opens the approval sheet for a prompt.

func appApproveOpen(prompt: AppApprovalPrompt) -> AppApproveSheetState

Parameter	Type	Default
`prompt`	`AppApprovalPrompt`	required

Returns AppApproveSheetState

`app_approve_reduce`#

Advances the approval sheet. devices is the account's current devices (for approving the waiting device of a code's name by id once the code expires).

func appApproveReduce(state: AppApproveSheetState, action: AppApproveSheetAction, devices: [AppDeviceInput]) -> AppApproveSheetState

Parameter	Type	Default
`state`	`AppApproveSheetState`	required
`action`	`AppApproveSheetAction`	required
`devices`	`Vec<AppDeviceInput>`	required

Returns AppApproveSheetState

`app_approve_sheet_action_from_json`#

An approval sheet action from JSON (parity flows).

func appApproveSheetActionFromJson(json: String) throws -> AppApproveSheetAction

Parameter	Type	Default
`json`	`String`	required

Returns AppApproveSheetAction · Raises CuaError

`app_approve_view`#

The approval sheet as drawn. devices is the account's current devices (see app_approve_reduce).

func appApproveView(state: AppApproveSheetState, devices: [AppDeviceInput]) -> AppApproveSheetView

Parameter	Type	Default
`state`	`AppApproveSheetState`	required
`devices`	`Vec<AppDeviceInput>`	required

Returns AppApproveSheetView

`app_confirm_presence`#

Asks the person at this computer to confirm reason ("approve “Work laptop” for your Cua account"). Returns when they did; fails with PermissionDenied when it was cancelled or not confirmed, or when this Mac has neither Touch ID nor a login password, and with Unsupported where the system has no usable prompt (Windows Hello not set up, no polkit agent or action), in words that say what is missing.

func appConfirmPresence(reason: String) async throws

Parameter	Type	Default
`reason`	`String`	required

Async · Raises CuaError (PermissionDenied, Unsupported)

`app_devices_clean_name`#

A device name as typed for Rename (None when empty).

func appDevicesCleanName(name: String) -> String?

Parameter	Type	Default
`name`	`String`	required

Returns Option<String>

`app_devices_input`#

The SDK's devices snapshot as the Devices page reads it (pending_code: the code this device shows while it waits).

func appDevicesInput(snapshot: DevicesSnapshot, pendingCode: String?) -> AppDevicesInput

Parameter	Type	Default
`snapshot`	`DevicesSnapshot`	required
`pending_code`	`Option<String>`	required

Returns AppDevicesInput

`app_devices_input_from_json`#

Devices page input from JSON (fixtures, parity flows).

func appDevicesInputFromJson(json: String) throws -> AppDevicesInput

Parameter	Type	Default
`json`	`String`	required

Returns AppDevicesInput · Raises CuaError

`app_devices_view`#

The Devices page at now (Unix seconds).

func appDevicesView(input: AppDevicesInput, now: UInt64) -> AppDevicesView

Parameter	Type	Default
`input`	`AppDevicesInput`	required
`now`	`u64`	required

Returns AppDevicesView

`app_enroll_action_from_json`#

An enroll sheet action from JSON (parity flows).

func appEnrollActionFromJson(json: String) throws -> AppEnrollAction

Parameter	Type	Default
`json`	`String`	required

Returns AppEnrollAction · Raises CuaError

`app_enroll_initial`#

The enroll sheet's first state.

func appEnrollInitial() -> AppEnrollState

Returns AppEnrollState

`app_enroll_reduce`#

Advances the enroll sheet.

func appEnrollReduce(state: AppEnrollState, action: AppEnrollAction) -> AppEnrollState

Parameter	Type	Default
`state`	`AppEnrollState`	required
`action`	`AppEnrollAction`	required

Returns AppEnrollState

`app_enroll_state_from_json`#

The enroll sheet's state from JSON (fixtures, parity).

func appEnrollStateFromJson(json: String) throws -> AppEnrollState

Parameter	Type	Default
`json`	`String`	required

Returns AppEnrollState · Raises CuaError

`app_enroll_view`#

The enroll sheet as drawn.

func appEnrollView(state: AppEnrollState) -> AppEnrollView

Parameter	Type	Default
`state`	`AppEnrollState`	required

Returns AppEnrollView

Devices

AppAuditInput record#

AppActivityRow record#

AppBannerTone enum#

AppThisDevice record#

AppEnrollmentKind enum#

AppApprovalPrompt record#

AppMachineInput record#

AppUnconfirmedMachine record#

app_machine_access_notice#

AppMachineAccessNotice record#

AppApproveRequest record#

AppApproveSheetState record#

AppApproveSheetView record#

AppDeviceBanner record#

AppDeviceConfirm record#

AppDeviceInput record#

AppDeviceRow record#

AppDevicesInput record#

AppDevicesLabels record#

AppDevicesView record#

AppEnrollOption record#

AppEnrollState record#

AppEnrollView record#

AppApproveSheetAction enum#

AppDeviceAction enum#

AppEnrollAction enum#

AppEnrollMethod enum#

AppEnrollPhase enum#

app_approve_open#

app_approve_reduce#

app_approve_sheet_action_from_json#

app_approve_view#

app_confirm_presence#

app_devices_clean_name#

app_devices_input#

app_devices_input_from_json#

app_devices_view#

app_enroll_action_from_json#

app_enroll_initial#

app_enroll_reduce#

app_enroll_state_from_json#

app_enroll_view#

AppAuditInput record#

AppActivityRow record#

AppBannerTone enum#

AppThisDevice record#

AppEnrollmentKind enum#

AppApprovalPrompt record#

AppMachineInput record#

AppUnconfirmedMachine record#

app_machine_access_notice#

AppMachineAccessNotice record#

AppApproveRequest record#

AppApproveSheetState record#

AppApproveSheetView record#

AppDeviceBanner record#

AppDeviceConfirm record#

AppDeviceInput record#

AppDeviceRow record#

AppDevicesInput record#

AppDevicesLabels record#

AppDevicesView record#

AppEnrollOption record#

AppEnrollState record#

AppEnrollView record#

AppApproveSheetAction enum#

AppDeviceAction enum#

AppEnrollAction enum#

AppEnrollMethod enum#

AppEnrollPhase enum#

app_approve_open#

app_approve_reduce#

app_approve_sheet_action_from_json#

app_approve_view#

app_confirm_presence#

app_devices_clean_name#

app_devices_input#

app_devices_input_from_json#

app_devices_view#

`AppAuditInput` record#

`AppActivityRow` record#

`AppBannerTone` enum#

`AppThisDevice` record#

`AppEnrollmentKind` enum#

`AppApprovalPrompt` record#

`AppMachineInput` record#

`AppUnconfirmedMachine` record#

`app_machine_access_notice`#

`AppMachineAccessNotice` record#

`AppApproveRequest` record#

`AppApproveSheetState` record#

`AppApproveSheetView` record#

`AppDeviceBanner` record#

`AppDeviceConfirm` record#

`AppDeviceInput` record#

`AppDeviceRow` record#

`AppDevicesInput` record#

`AppDevicesLabels` record#

`AppDevicesView` record#

`AppEnrollOption` record#

`AppEnrollState` record#

`AppEnrollView` record#

`AppApproveSheetAction` enum#

`AppDeviceAction` enum#

`AppEnrollAction` enum#

`AppEnrollMethod` enum#

`AppEnrollPhase` enum#

`app_approve_open`#

`app_approve_reduce`#

`app_approve_sheet_action_from_json`#

`app_approve_view`#

`app_confirm_presence`#

`app_devices_clean_name`#

`app_devices_input`#

`app_devices_input_from_json`#

`app_devices_view`#

`app_enroll_action_from_json`#

`app_enroll_initial`#

`app_enroll_reduce`#

`app_enroll_state_from_json`#

`app_enroll_view`#

`AppAuditInput` record#

`AppActivityRow` record#

`AppBannerTone` enum#

`AppThisDevice` record#

`AppEnrollmentKind` enum#

`AppApprovalPrompt` record#

`AppMachineInput` record#

`AppUnconfirmedMachine` record#

`app_machine_access_notice`#

`AppMachineAccessNotice` record#

`AppApproveRequest` record#

`AppApproveSheetState` record#

`AppApproveSheetView` record#

`AppDeviceBanner` record#

`AppDeviceConfirm` record#

`AppDeviceInput` record#

`AppDeviceRow` record#

`AppDevicesInput` record#

`AppDevicesLabels` record#

`AppDevicesView` record#

`AppEnrollOption` record#

`AppEnrollState` record#

`AppEnrollView` record#

`AppApproveSheetAction` enum#

`AppDeviceAction` enum#

`AppEnrollAction` enum#

`AppEnrollMethod` enum#

`AppEnrollPhase` enum#

`app_approve_open`#

`app_approve_reduce`#

`app_approve_sheet_action_from_json`#

`app_approve_view`#

`app_confirm_presence`#

`app_devices_clean_name`#

`app_devices_input`#

`app_devices_input_from_json`#

`app_devices_view`#

`app_enroll_action_from_json`#