Skip to content

Registering Devices

<!-- AUTOMATION_METADATA_START screenshot_source_url: https:///devices/screenshot?screenshot=1 AUTOMATION_METADATA_END -->

This guide explains how to register a laptop or workstation so it can request SSH access through SSH Teams.

<!-- Automation screenshot source URL: https:///devices/screenshot?screenshot=1 -->

Before You Start

Make sure you have:

  • The sshteam CLI installed on the device.
  • A browser available to approve the registration.
  • A valid SSH Teams user account.
  • A trusted certificate on your SSH Teams server for production use.

What Device Registration Means

When you register a device, you link it to your SSH Teams user account. The device can then request short-lived access passes when you connect to servers.

Think of it like pairing your phone with an app, but for SSH access.

Start Registration

Run this command in a terminal on the device:

sshteam init https://<hostname>

You can also leave off https:// and just use the hostname:

sshteam init my-sshteam.example.com

The CLI will show a web link and a short code.

Approve the Device in Your Browser

  1. Open the link shown by the CLI.
  2. Sign in to SSH Teams if asked.
  3. Review the device details.
  4. Click Approve.

Device verification form

Device approval success page

After approval, the CLI finishes setup automatically.

What Happens Next

Once approved, the device stores a secure token locally. This token is used to request access passes when you connect to servers.

Tokens are refreshed automatically, so you rarely need to register again. If the device is lost, stolen, or no longer needed, you can revoke it from the dashboard.

Default timing:

  • Device codes expire after 10 minutes.
  • Access passes are valid for 24 hours.
  • Refresh tokens are valid for 30 days.

Two Different Flows

The sshteam init command uses a registration flow for user devices. Server join scripts use a separate flow for adding servers. They are not the same thing.

View and Revoke Devices

  1. Sign in to SSH Teams.
  2. Go to My Devices.

My devices list

To remove a device:

  1. Find it in the list.
  2. Click Revoke.
  3. Confirm.

The device will no longer be able to request access. If you revoke by mistake, run sshteam init again to re-register.

My devices list with revoked device

Fixing Common Device Problems

  • The code expired before approval.

    • Run sshteam init https://<hostname> again and approve promptly.

  • Approval was denied.

    • Run the command again and make sure to click Approve.

  • The CLI waits a long time and then times out.

    • Make sure you opened the exact URL shown by the CLI.
    • Check that the code on the page matches the one in the terminal.

  • You see an invalid device proof error.

    • Re-register the device. This creates a fresh token pair.

  • Access fails after revoking a device.

    • This is expected. Re-register the device if you still need access.

  • Access fails after a long time.

    • The refresh token may have expired. Run sshteam init https://<hostname> again.