Skip to content →
Log in

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.create permission, 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#

  1. 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.
  2. You open the Console’s Authorize Device page, normally at console.pulseha.com/device, and approve the code.
  3. The control plane creates the device record (or reuses yours), binds it to your user and organisation, and marks the code authorized.
  4. The agent’s next poll succeeds, it registers, and the device goes Online.

Approve the device#

  1. Start login on the device:
    • Linux: run pulsectl login and choose Browser (device code). The terminal prints a URL and Your code.
    • Windows or macOS: open PulseHA and choose Continue in Browser.
  2. Open the URL. If you are not signed in, the Console sends you to login and back again.
  3. 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 page with a device code typed into the Device Code field

Authorize Device with a code entered. The title switches to Authorize Gateway if the code came from a gateway.

  1. The page shows Device authorized. Return to your client to finish. with a View devices link.

Authorize Device page in its approved state with a View devices link

The approved state. View devices takes you to the new row in Network, Devices.

  1. 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#

StateHow it happensHow to leave it
PendingCode approved, agent not yet registeredAgent registers and heartbeats
OnlineHeartbeat within the last 4 minutesNormal
OfflineNo heartbeat for a while; the control plane marks idle agents inactive after about 5 minutesAgent reconnects
ArchivedOperator chose Archive Device, or no heartbeat for 90 daysOperator chooses Restore Device
BlockedOperator chose Block Device (intended for lost or stolen devices)Operator chooses Restore Device
RevokedOperator chose Revoke DeviceSame 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 symptomCause and fix
invalid or expired device codeThe code was mistyped, or it is older than 15 minutes. Start login again on the device.
device code already usedEach code is single-use. Request a fresh one from the agent.
device code expiredThe 15-minute window passed between request and approval. Retry.
Device-limit messageYou 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 mismatchYou 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 outThe agent gave up waiting. Run pulsectl login again.
Row stays PendingApproval 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.