POST/link/v1/enrolments/add
Open an enrolment for a device key
Called by a Link agent that is not yet a device. No credential: the gateway limits this route per address, and requires an Idempotency-Key; retrying with the same key and body after a lost response returns the original.
Returns the enrolment, its userCode and approvalUriComplete for the person, and secret, shown once. The secret authenticates enrolments/get, enrolments/remove and devices/add for this enrolment only.
- Scope
- link:enrolments:add Admin-issued keys only.
- Idempotency
- Requires an
Idempotency-Keyheader. Reusing the key within 24 hours returns the original response instead of creating a second record.
Request bodyapplication/json
| Field | Type | Description |
|---|---|---|
| protocolrequired | integer | Must be 1. |
| keyAlgorithmrequired | string | one of "ES256" |
| publicKeyrequired | string | The device's P-256 public key, SPKI DER encoded, base64url without padding.80 to 200 characters · matches ^[A-Za-z0-9_-]+$ |
| platformrequired | string | One of: windows, linux, android.up to 32 characters |
| displayName | string | 1 to 64 characters |
| platformVersion | string | 1 to 64 characters |
| agentVersion | string | 1 to 32 characters |
Request body of addEnrolment
- protocolrequired
- Type
- integer
- Description
- Must be 1.
- keyAlgorithmrequired
- Type
- string
- Description
- one of "ES256"
- publicKeyrequired
- Type
- string
- Description
- The device's P-256 public key, SPKI DER encoded, base64url without padding.80 to 200 characters · matches ^[A-Za-z0-9_-]+$
- platformrequired
- Type
- string
- Description
- One of: windows, linux, android.up to 32 characters
- displayName
- Type
- string
- Description
- 1 to 64 characters
- platformVersion
- Type
- string
- Description
- 1 to 64 characters
- agentVersion
- Type
- string
- Description
- 1 to 32 characters
Response 200Enrolment opened
| Field | Type | Description |
|---|---|---|
| datarequired | LinkEnrolmentCreated | |
| enrolmentrequired | LinkEnrolment | |
| secretrequired | string | The enrolment secret, shown once. Send it as Authorization: Bearer to enrolments/get, enrolments/remove and devices/add. |
Response of addEnrolment
- datarequired
- Type
- LinkEnrolmentCreated
- Description
- enrolmentrequired
- Type
- LinkEnrolment
- Description
- secretrequired
- Type
- string
- Description
- The enrolment secret, shown once. Send it as
Authorization: Bearerto enrolments/get, enrolments/remove and devices/add.
Errors
Each is an RFC 7807 problem document whose type URL is a page in the error reference.
- 400Unsupported protocol or platform, an invalid public key, or a malformed request
- 409The key is already an active device, or belonged to a revoked one
Example
curl -X POST https://api.rsx.group/link/v1/enrolments/add \
-H "Authorization: Bearer rsx_live_..." \
-H "Idempotency-Key: 5b8f2d1a-0c7e-4b1f-9a6d-3e2f1c0b9a8d" \
-H "Content-Type: application/json" \
-d '{
"protocol": 1,
"keyAlgorithm": "ES256",
"publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEyVDx2fAX3rA6m0EIUzBBWkA4zG6-n9t9Sb8c2X5wXn0q2xvGQaU2C9Uw8Yw4rX4n2m4R3x8Gm8fGJf9k5Yy3sA",
"platform": "windows",
"displayName": "Ada'\''s desktop",
"platformVersion": "Windows 11 Pro 24H2",
"agentVersion": "0.2.0"
}'{
"data": {
"enrolment": {
"id": "0199d6a1-3b2c-7d4e-8f50-6a7b8c9d0e1f",
"state": "pending",
"userCode": "BCDF-GHJK",
"approvalUri": "https://id.rsx.group/link",
"approvalUriComplete": "https://id.rsx.group/link?code=BCDF-GHJK",
"keyFingerprint": "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs",
"createdAt": "2026-10-13T12:00:00.000Z",
"expiresAt": "2026-10-13T12:00:00.000Z",
"pollIntervalSeconds": 5,
"challenge": null,
"deviceId": null
},
"secret": "rsx_lke_Zm9vYmFyYmF6cXV4cXV1eGNvcmdlZ3JhdWx0Z2FycGx5"
}
}