Authorize a device
Bind a new endpoint to your user and organization.
Authorising a device links an installed agent to your user account and your organisation. The agent shows a short code; you approve that code in the Console while signed in. This page explains the flow, the rules the control plane applies, and what each error means.
Before you start#
- The agent must already be installed. See Install the agent.
- You need a Console account in the organisation. Approving a device requires the
devices.createpermission, which the owner, admin and user roles have by default. - If your organisation requires SSO, the browser session you approve from must satisfy it.
- Each user may hold up to 5 devices per organisation. Re-authorising a device you already own, including a revoked one, reuses the existing record and does not count.
How the flow works#
- The agent asks the control plane for a device code. The code is valid for 15 minutes and the agent polls for approval every few seconds.
- You open the Console’s Authorize Device page, normally at
console.pulseha.com/device, and approve the code. - The control plane creates the device record (or reuses yours), binds it to your user and organisation, and marks the code authorized.
- The agent’s next poll succeeds, it registers, and the device goes Online.
Approve the device#
- Start login on the device:
- Linux: run
pulsectl loginand choose Browser (device code). The terminal prints a URL and Your code. - Windows or macOS: open PulseHA and choose Continue in Browser.
- Linux: run
- Open the URL. If you are not signed in, the Console sends you to login and back again.
- On Authorize Device, the subtitle reads Enter the code displayed on your device. If the code was in the URL it is filled in and approved automatically once you are signed in. Otherwise type it into Device Code (format
ABCD-1234) and choose Authorize Device.

Authorize Device with a code entered. The title switches to Authorize Gateway if the code came from a gateway.
- The page shows Device authorized. Return to your client to finish. with a View devices link.

The approved state. View devices takes you to the new row in Network, Devices.
- Back on the device, the CLI prints Signed in as <email>, or the app finishes sign-in.
The page also detects gateway codes. If you paste a code produced by sudo pulseha-gateway login, the title changes to Authorize Gateway and approving it additionally requires the gateways.create permission.
What you should see#
Open Network → Devices. The device row shows the hostname with your email underneath, which confirms the user binding. Connection reads Pending until the agent registers, then Online.
Device states after authorisation#
| State | How it happens | How to leave it |
|---|---|---|
| Pending | Code approved, agent not yet registered | Agent registers and heartbeats |
| Online | Heartbeat within the last 4 minutes | Normal |
| Offline | No heartbeat for a while; the control plane marks idle agents inactive after about 5 minutes | Agent reconnects |
| Archived | Operator chose Archive Device, or no heartbeat for 90 days | Operator chooses Restore Device |
| Blocked | Operator chose Block Device (intended for lost or stolen devices) | Operator chooses Restore Device |
| Revoked | Operator chose Revoke Device | Same user signs in again from the device; the record is reused |
Archive Device, Block Device, Restore Device and Revoke Device live in the device drawer’s action menu and need the devices.revoke permission (owner or admin). Restoring puts the device back to inactive; it becomes Online on its next heartbeat.
Troubleshooting#
| Message or symptom | Cause and fix |
|---|---|
| invalid or expired device code | The code was mistyped, or it is older than 15 minutes. Start login again on the device. |
| device code already used | Each code is single-use. Request a fresh one from the agent. |
| device code expired | The 15-minute window passed between request and approval. Retry. |
| Device-limit message | You already have 5 devices here. Ask an owner or admin to revoke one, or re-enrol an existing device of yours instead of a new one. |
| tenant mismatch | You are signed in to a different organisation than the one the code belongs to. Sign out of the Console and sign in with the right account. |
| Your session has expired. Please refresh the page and try again. | The Console session lapsed while the page was open. Refresh and sign in. |
| CLI prints login timed out | The agent gave up waiting. Run pulsectl login again. |
| Row stays Pending | Approval worked but the agent has not registered. On Linux check pulsectl status; on Windows or macOS reopen the app. |
Enrollment tokens (pulsectl login --token) and OIDC workload identity (pulsectl login --oidc-token --tenant) are alternatives for servers and automation. They do not replace the browser flow for user devices.