# Device Agent Authentication

Agentul de dispozitivAPIutilizează două credențiale cu scopuri diferite:

| Credential       | Purpose                                       | Sent as                           |
| ---------------- | --------------------------------------------- | --------------------------------- |
| Enrollment token | One-time exchange for a device API key        | `token` in the `/enroll` body     |
| Device API key   | Heartbeat, posture, and unenrollment requests | `Authorization: Bearer <api-key>` |

Ambele credențiale sunt șiruri hexadecimale de 96 de caractere. platforma stochează numai hash-urile lor SHA-256 .

## Enrollment tokens

Un token de înscriere aparține unei singure înregistrări a dispozitivului. Este de unică folosință și expiră după șapte zile în mod implicit.

Creați dispozitivul și obțineți tokenul său înainte de a apela Agentul dispozitivuluiAPI:

- In the the platform console, use the device enrollment flow.
- Through the console GraphQL API, use `createDevice` or `enrollDevice`.
- Through MCP, use the `createDevice` tool.
- Through the CLI, use [`prb device create`](/docs/developers/cli/commands/device).
- Through n8n, use the [device create](/docs/developers/api/n8n/resources/device) operation.

Those interfaces return the the platform server URL alongside the token. Device
creation is not part of `/api/agent/v1`.

:::precauție[Protejează jetoanele de înscriere] Nu introduceți un jetoan de înscriere într-un URL web obișnuit, jurnal, istoric de shell sau mesaj de chat. Oricine îl schimbă înainte de expirarea acestuia primește cheiaAPIa dispozitivului. :::

## Exchange a token

Trimiteți tokenul o dată la URL-ul serverului furnizat cu înscrierea:

  

```bash
curl --request POST \
  --url https://us.probo.com/api/agent/v1/enroll \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"token":"<enrollment-token>"}'
```

  
  

```bash
curl --request POST \
  --url https://eu.probo.com/api/agent/v1/enroll \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"token":"<enrollment-token>"}'
```

  
  

```bash
curl --request POST \
  --url https://probo.example.com/api/agent/v1/enroll \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"token":"<enrollment-token>"}'
```

  

A successful exchange returns:

```json
{
  "api_key": "<device-api-key>"
}
```

The server deletes the enrollment token after the exchange. Reusing it, using
an expired token, or using an unknown token returns `401 Unauthorized`.

Persistați cheiaAPIînainte de a începe serviciul. agentul oficial îl stochează în directorul său de stat cu acces restricționat la contul de serviciu. un agent personalizat poate folosi în schimb magazinul secret al sistemului de operare.

## Authenticate device requests

Send the device API key as a bearer token on every endpoint except `/enroll`:

```http
Authorization: Bearer <device-api-key>
```

For example:

```bash
curl --request POST \
  --url https://us.probo.com/api/agent/v1/heartbeat \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <device-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "hardware_uuid": "example-hardware-id",
    "hostname": "example-device",
    "platform": "LINUX",
    "os_version": "Example Linux 1.0",
    "agent_version": "1.0.0"
  }'
```

CheiaAPIrămâne valabilă până când dispozitivul este revocat de un administrator sau dezinserat de agent. platforma afișează cheia de text simplu numai în răspunsul de înscriere.

## Handle unauthorized responses

Treat any `401 Unauthorized` response from an authenticated endpoint as a dead
credential:

1. Opriți încărcarea bătăilor inimii și a posturii. 2. ștergeți cheiaAPIși datele de postură în coadă din stocarea locală. 3. necesită un nou token de înregistrare și înregistrare a dispozitivului.

Do not retry a rejected API key indefinitely.

One important exception during bring-up: `/postures` also returns `401` when the
device is still `PENDING` because no successful heartbeat has activated it yet.
Activate with `/heartbeat` before the first posture upload so a valid key is not
cleared as revoked.

## Desktop enrollment links

Fluxul oficial de desktop poate trece intrarea de înscriere prin această URI particularizată:

```text
probo://enroll?server=https%3A%2F%2Fus.probo.com&token=<enrollment-token>
```

If your agent implements this flow, register the `probo` scheme securely,
validate that `server` is an HTTPS origin, reject unexpected parameters, and
avoid logging the URI. A custom URI is optional; command-line and managed
installation flows can pass the server and token separately.

## Next step

Consultați [Endpoints](/docs/developers/api/agent/endpoints) pentru schemele de solicitare și răspuns.