API referenceConsumerConsumer.device auth
Register a device with an auth key
Registers or reuses a machine-keyed device in the selected project using a raw auth key, issues a fresh device session token pair, and records auth-key usage.
Header Parameters
X-Project-Id*string
UUID of the project that scopes consumer accounts, devices, sessions, and VSpaces for the request.
Format
uuidRequest Body
application/json
Auth-key-backed device registration payload for the selected project.
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/consumer/v1/auth/device/register" \ -H "X-Project-Id: 11111111-1111-1111-1111-111111111111" \ -H "Content-Type: application/json" \ -d '{ "auth_key": "fvpn-ak_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "machine_key": "AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE=", "name": "prod-server-01", "node_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=", "platform": "linux" }'{ "device": { "addresses": { "ipv4": "100.101.0.14", "ipv6": "fd7a:115c:a1e0:efe3::14", "vspace_id": "44444444-4444-4444-4444-444444444444" }, "consumer_account_id": "22222222-2222-2222-2222-222222222222", "created_at": "2026-04-12T09:45:00Z", "ephemeral": true, "id": "55555555-5555-5555-5555-555555555555", "machine_key": "AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE=", "name": "prod-server-01", "node_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=", "platform": "linux", "status": "active", "tags": [ "role:server" ], "updated_at": "2026-04-12T10:00:00Z", "user_id": "33333333-3333-3333-3333-333333333333" }, "session": { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.consumer-access.signature", "device_id": "55555555-5555-5555-5555-555555555555", "expires_in": 900, "refresh_token": "forestvpn-refresh-token-demo", "session_id": "66666666-6666-6666-6666-666666666666" }}{ "detail": "Pool slug must be unique.", "instance": "urn:forestvpn:trace:a1b2c3d4", "title": "Validation Error", "type": "https://fvpn.net/errors/validation"}{ "detail": "Pool slug must be unique.", "instance": "urn:forestvpn:trace:a1b2c3d4", "title": "Validation Error", "type": "https://fvpn.net/errors/validation"}{ "detail": "Pool slug must be unique.", "instance": "urn:forestvpn:trace:a1b2c3d4", "title": "Validation Error", "type": "https://fvpn.net/errors/validation"}