Devices API

The devices API manages the Ed25519-based device identity system and the pairing code flow for authorizing new devices without a username/password.

Device Identity

Each profClaw instance generates a unique Ed25519 key pair on first run (src/auth/device-identity.ts). The public key serves as the device’s identity for attestations and pairing.

GET /api/devices/identity

Get the current device’s public identity.

curl http://localhost:3000/api/devices/identity

Response 200

{
  "deviceId": "dev_01a2b3c4",
  "publicKey": "base64-encoded-ed25519-public-key",
  "fingerprint": "sha256:abc123..."
}

POST /api/devices/attest

Create a signed attestation for the current device.

curl -X POST http://localhost:3000/api/devices/attest \
  -d '{"data": {"purpose": "pairing"}}'

Response 200

{
  "attestation": {
    "deviceId": "dev_01",
    "publicKey": "...",
    "attestation": {
      "timestamp": "2026-03-12T10:00:00Z",
      "nonce": "random-nonce",
      "data": { "purpose": "pairing" },
      "signature": "base64-signature"
    }
  }
}

POST /api/devices/verify

Verify an attestation from another device.

curl -X POST http://localhost:3000/api/devices/verify \
  -d '{
    "attestation": { "deviceId": "...", "publicKey": "...", "attestation": {...} },
    "maxAgeMs": 60000
  }'

Pairing Codes

Pairing codes let a new device (phone, second computer) connect to profClaw without password entry.

POST /api/devices/pairing/request

Request a pairing code from the new device side.

curl -X POST http://localhost:3000/api/devices/pairing/request \
  -d '{"requesterId": "mobile-app-id", "meta": {"platform": "ios"}}'

Response 200

{
  "requestId": "pair_01",
  "code": "ABC-123-XYZ",
  "formatted": "ABC 123 XYZ",
  "expiresAt": "2026-03-12T10:10:00Z"
}

Codes expire after 10 minutes.

POST /api/devices/pairing/approve

Approve a pending pairing request (from the already-trusted device).

curl -X POST http://localhost:3000/api/devices/pairing/approve \
  -d '{"code": "ABC-123-XYZ", "approvedBy": "usr_01"}'

POST /api/devices/pairing/reject

Reject a pairing request.

GET /api/devices/pairing/status/:requestId

Check if a pairing request has been approved.

curl http://localhost:3000/api/devices/pairing/status/pair_01

Response 200

{
  "status": "approved",
  "token": "session-token-for-new-device",
  "approvedAt": "2026-03-12T10:01:00Z"
}

GET /api/devices/pairing/pending

List all pending pairing requests (admin only).

QR Pairing

For mobile/desktop onboarding without typing codes:

GET /api/devices/pairing/qr

Generate a QR code for the pairing flow.

curl http://localhost:3000/api/devices/pairing/qr

Response 200

{
  "qrSvg": "<svg>...</svg>",
  "pairingUrl": "profclaw://pair?code=ABC-123-XYZ&host=my-server.local",
  "requestId": "pair_01",
  "expiresAt": "2026-03-12T10:10:00Z"
}

Display the SVG to the user and poll GET /api/devices/pairing/status/:requestId until approved.

Cleanup

POST /api/devices/pairing/cleanup

Remove expired pairing requests. Run periodically or call after your own cleanup schedule.

Authentication API - Session and OAuth-based authentication
Security Device Pairing - How device pairing works and security model
profclaw device - Manage paired devices from the CLI
Security Overview - Auth modes and trust management

API Overview

Authentication

Chat

Agents

Tasks

Memory

Integrations

System

Device Identity

GET /api/devices/identity

POST /api/devices/attest

POST /api/devices/verify

Pairing Codes

POST /api/devices/pairing/request

POST /api/devices/pairing/approve

POST /api/devices/pairing/reject

GET /api/devices/pairing/status/:requestId

GET /api/devices/pairing/pending

QR Pairing

GET /api/devices/pairing/qr

Cleanup

​Device Identity

​GET /api/devices/identity

​POST /api/devices/attest

​POST /api/devices/verify

​Pairing Codes

​POST /api/devices/pairing/request

​POST /api/devices/pairing/approve

​POST /api/devices/pairing/reject

​GET /api/devices/pairing/status/:requestId

​GET /api/devices/pairing/pending

​QR Pairing

​GET /api/devices/pairing/qr

​Cleanup

​Related

Device Identity

GET /api/devices/identity

POST /api/devices/attest

POST /api/devices/verify

Pairing Codes

POST /api/devices/pairing/request

POST /api/devices/pairing/approve

POST /api/devices/pairing/reject

GET /api/devices/pairing/status/:requestId

GET /api/devices/pairing/pending

QR Pairing

GET /api/devices/pairing/qr

Cleanup

Related