Diff: how-to/pair-a-new-device
From 1c02ec1 to 1c02ec1
+0 / −0 lines
| Before | After |
|---|---|
| --- | --- |
| schema: foundry-doc-v1 | schema: foundry-doc-v1 |
| title: "How to pair a new device" | title: "How to pair a new device" |
| slug: pair-a-new-device | slug: pair-a-new-device |
| category: how-to | category: how-to |
| content_type: how-to | content_type: how-to |
| type: how-to | type: how-to |
| status: active | status: active |
| last_edited: 2026-06-14 | last_edited: 2026-06-14 |
| editor: pointsav-engineering | editor: pointsav-engineering |
| paired_with: pair-a-new-device.es.md | paired_with: pair-a-new-device.es.md |
| --- | --- |
| Pairing a device registers it with the platform using machine-based authorization — a cryptographic handshake that binds access to your hardware rather than to a username and password. Once a device is paired, it holds the keys required to establish connections. A device without a pairing has no pathway to the protected resources at all — not access-denied, but structurally unreachable. | Pairing a device registers it with the platform using machine-based authorization — a cryptographic handshake that binds access to your hardware rather than to a username and password. Once a device is paired, it holds the keys required to establish connections. A device without a pairing has no pathway to the protected resources at all — not access-denied, but structurally unreachable. |
| For the theory behind this model, see [[machine-based-auth]] and [[pairing-as-permission]]. | For the theory behind this model, see [[machine-based-auth]] and [[pairing-as-permission]]. |
| ## Prerequisites | ## Prerequisites |
| - A PointSav account with at least P3 access (see [[personnel-permissions]]) | - A PointSav account with at least P3 access (see [[personnel-permissions]]) |
| - The `os-console` application installed on the device you are pairing | - The `os-console` application installed on the device you are pairing |
| - Network access to the Command endpoint assigned to your account | - Network access to the Command endpoint assigned to your account |
| ## Steps | ## Steps |
| ### 1. Open the pairing request from os-console | ### 1. Open the pairing request from os-console |
| Launch `os-console` on the new device and navigate to **Settings → Devices → Pair this device**. The console generates a temporary pairing code — a short, human-readable string that is valid for 10 minutes. | Launch `os-console` on the new device and navigate to **Settings → Devices → Pair this device**. The console generates a temporary pairing code — a short, human-readable string that is valid for 10 minutes. |
| ### 2. Approve the pairing on a trusted device | ### 2. Approve the pairing on a trusted device |
| On a device already paired to your account (your INPUT-tier daily machine), open `os-console` and navigate to **Settings → Devices → Pending pairings**. The new device's pairing code and hardware fingerprint appear here. | On a device already paired to your account (your INPUT-tier daily machine), open `os-console` and navigate to **Settings → Devices → Pending pairings**. The new device's pairing code and hardware fingerprint appear here. |
| Verify that the fingerprint shown on the new device matches the fingerprint shown on your trusted device before approving. This cross-check prevents a rogue device from inserting itself. | Verify that the fingerprint shown on the new device matches the fingerprint shown on your trusted device before approving. This cross-check prevents a rogue device from inserting itself. |
| ### 3. Select the pairing type | ### 3. Select the pairing type |
| Choose the access tier for the new device: | Choose the access tier for the new device: |
| | Tier | What it can do | | | Tier | What it can do | |
| |---|---| | |---|---| |
| | INPUT | Full read/write access to your archives and data — use for your daily machine | | | INPUT | Full read/write access to your archives and data — use for your daily machine | |
| | USER | Read-only access — use for shared or secondary devices | | | USER | Read-only access — use for shared or secondary devices | |
| | INTERFACE | Metadata only — use for orchestration and monitoring integrations | | | INTERFACE | Metadata only — use for orchestration and monitoring integrations | |
| ADMIN pairings require the approval of the system administrator and cannot be self-issued. | ADMIN pairings require the approval of the system administrator and cannot be self-issued. |
| ### 4. Confirm and complete | ### 4. Confirm and complete |
| Approve the pairing from your trusted device. The new device's `os-console` refreshes automatically and the Totebox session becomes available. The pairing event is recorded to the audit ledger immediately. | Approve the pairing from your trusted device. The new device's `os-console` refreshes automatically and the Totebox session becomes available. The pairing event is recorded to the audit ledger immediately. |
| ## Verify the pairing | ## Verify the pairing |
| On the new device, open `os-console` and navigate to **Settings → Devices → This device**. The device status should show **Paired** with the tier you selected and the timestamp of the pairing event. | On the new device, open `os-console` and navigate to **Settings → Devices → This device**. The device status should show **Paired** with the tier you selected and the timestamp of the pairing event. |
| Run a test read-operation on any archive to confirm connectivity. | Run a test read-operation on any archive to confirm connectivity. |
| ## Revoke a pairing | ## Revoke a pairing |
| To remove a device from your account, navigate to **Settings → Devices** on any paired device, select the target device, and choose **Revoke**. The revoked device becomes mutually invisible to your resources immediately — no logout or TTL wait is required. | To remove a device from your account, navigate to **Settings → Devices** on any paired device, select the target device, and choose **Revoke**. The revoked device becomes mutually invisible to your resources immediately — no logout or TTL wait is required. |
| ## Key takeaways | ## Key takeaways |
| - The pairing IS the permission; there is no central access-control list to update | - The pairing IS the permission; there is no central access-control list to update |
| - Always verify the hardware fingerprint cross-check before approving a new pairing | - Always verify the hardware fingerprint cross-check before approving a new pairing |
| - INPUT pairings grant full read/write access — assign them to machines you control directly | - INPUT pairings grant full read/write access — assign them to machines you control directly |
| - Revocation is immediate and hardware-level; no session or token expiry needed | - Revocation is immediate and hardware-level; no session or token expiry needed |
| ## See also | ## See also |
| - [[machine-based-auth]] — how machine-based authorization works architecturally | - [[machine-based-auth]] — how machine-based authorization works architecturally |
| - [[pairing-as-permission]] — the Object Capability pattern that pairing implements | - [[pairing-as-permission]] — the Object Capability pattern that pairing implements |
| - [[personnel-permissions]] — the four access tiers and what each can do | - [[personnel-permissions]] — the four access tiers and what each can do |
| - [[open-first-totebox-session]] — open a session on a newly paired device | - [[open-first-totebox-session]] — open a session on a newly paired device |