---
title: "Register a device in your own tree"
method: POST
path: "/api/v1/devices"
tags: ["Devices"]
---

# Register a device in your own tree

`POST /api/v1/devices`

## Request

- Base URL: `https://saltapp.ai`
- URL: `https://saltapp.ai/api/v1/devices`
- Auth: API key in header `api-key`

Called by the desktop app, which generated the keypair. Send only the public key; Salt derives the fingerprint and refuses any private key. The device's api-key is returned once and is valid only on the device and lane endpoints.

## Request body

- object
  - `name` string, required
  - `platform` 'macos' | 'windows', required
  - `public_key` string, required
  - `app_version` string: The Salt Device version this computer runs.
  - `app_commit` string: The git commit of that build (7-40 hex).
  - `machine_id` string: Opaque, stable install id of this machine. Re-registering the same machine_id under the same owner reuses the same device (same id, new key, old api-keys revoked, open sessions ended). Without it, a device of the same name and platform that has no machine_id is reused.

## Response `201`

Created, or the existing device re-registered (same id) when machine_id matches.

- object
  - `id` string
  - `name` string
  - `platform` 'macos' | 'windows'
  - `username` string
  - `public_fingerprint` string
  - `owner_id` string
  - `created_at` string, date-time
  - `socket_seen_at` string, date-time, nullable
  - `app_version` string, nullable: The Salt Device version this computer runs (e.g. `0.2.2`), as the device reported it. Null until it has.
  - `app_commit` string, nullable: The git commit that build was made from (7-40 lowercase hex). Null until reported.
  - `live_session` boolean
  - `public_key` string: The computer's armored public key: what a person encrypts a live-view offer to, and verifies its answer against.
  - `fingerprint` string: The same fingerprint as `public_fingerprint`.
  - `can_watch` boolean: Salt Device 0.4 or newer on a Mac: this computer can show its screen live.
  - `watching` object[], nullable: `GET /devices` only, for the device's owner and root: who is watching its screen now. Null for anyone else.
    - `viewer_id` string
    - `call_id` string
  - `offline_since` string, date-time, nullable: `GET /devices` only. When the computer is not online (no live session holds it and its socket was not seen in the last 5 minutes): the time it was last seen. Null when online or never seen.
  - `lost_contact` object, nullable: `GET /devices` only, for the device's owner and root. Set when the most recent session that worked on this computer ended `lost_contact` (it stopped answering for 15 seconds) and the computer has not been seen alive since; null otherwise.
    - `agent_id` string
    - `agent_name` string
    - `ended_at` string, date-time
  - `api_key` string: Returned once, on create only.

## Other responses

- `401`: Missing or invalid credentials.
- `403`: A keyless agent cannot register a device.
- `404`: Not found, or the feature is off.
- `422`: Bad name, platform, key, app_version or app_commit, or a private key was sent.

---

[API](https://skmtc.dev/saltapp/apis/salt-agent-api.md) · [All operations](https://skmtc.dev/saltapp/apis/salt-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/saltapp/apis/salt-agent-api/revisions/a8b8642ab7f8?raw)