Clawkey

Register your agent under your human owner powered by VeryAI palm verification. The agent starts registration with a signed challenge showing it controls its key; the human opens a URL and completes VeryAI's palm verification. Once the human finishes, the agent is registered under their ownership and can be verified by third parties.

> **CRITICAL: Never open browsers**
>
> Do **not** use `open`, `xdg-open`, `start`, or any command that opens a browser. Always output the **registration URL** as a text or markdown link for the user to click.
>
> - WRONG: `open "https://api.very.org/oauth2/..."`
> - CORRECT: "Open this link to complete verification: https://api.very.org/oauth2/..."

## Key files

| File         | Purpose                                                                                   |
| ------------ | ----------------------------------------------------------------------------------------- |
| SKILL.md     | https://clawkey.ai/skill.md — registration flow, challenge generation, verification, API  |
| HEARTBEAT.md | https://clawkey.ai/heartbeat.md — periodic checklist: registration status, etc            |
| Identity     | `~/.openclaw/identity/device.json` — OpenClaw deviceId and keys (do not send private key) |

## Security

- **Private key**: Used to sign the challenge. Never send the private key to ClawKey or any server; only send `publicKey`, `message`, and `signature`.
- **Registration URL**: Single-use and short-lived. Give it only to the human owner who will complete VeryAI palm verification.
- **deviceId**: Use a stable identifier (e.g. from your identity store or hash of public key). It ties the agent to the registration and is used for lookup and verification.

## Generating the AgentChallenge

The **AgentChallenge** is a signed payload that shows you control an Ed25519 key. It has the shape used by standard OpenClaw identity flows: `deviceId`, `publicKey`, `message`, `signature`, `timestamp`. Generate it once and send it to `/agent/register/init` or `/agent/verify/signature`.

### Where identity comes from (OpenClaw)

If you run on OpenClaw, device identity is stored at:

- **Path:** `~/.openclaw/identity/device.json`

That file contains (never send `privateKeyPem` to any server):

| Field           | Use                                                                      |
| --------------- | ------------------------------------------------------------------------ |
| `deviceId`      | Use as `deviceId` in the challenge. Stable id for this agent/device.     |
| `publicKeyPem`  | Use to derive `publicKey` (see below).                                   |
| `privateKeyPem` | Use only locally to sign the message. **Never include in API requests.** |

If you don’t use OpenClaw, use your own identity store; ensure you have a stable `deviceId`, an Ed25519 key pair, and that you sign the **exact** string you send as `message`.

### Build the challenge (step-by-step)

1. **Choose the message to sign**  
   For registration, use a one-time challenge to avoid replay, e.g.:
   - `clawkey-register-<unix_timestamp_ms>`  
     Example: `clawkey-register-1738500000000`  
     For verify/signature, the message is whatever you are proving (e.g. a nonce from a third party).

2. **Sign the message** with your Ed25519 **private** key. The signature must be over the **exact** UTF-8 bytes of `message` (no extra prefix/suffix).

3. **Encode for the API:**
   - **publicKey**: Ed25519 public key in **SPKI DER** form, then **base64** (no PEM wrapper).
   - **signature**: Raw Ed25519 signature bytes, **base64**.
   - **timestamp**: Unix time in **milliseconds** when the challenge was created (e.g. `Date.now()`).

4. **JSON body (AgentChallenge):**
   - `deviceId` — from your identity (e.g. `device.json`)
   - `publicKey` — base64 DER SPKI
   - `message` — exact string that was signed
   - `signature` — base64 signature
   - `timestamp` — number (ms)

### Example: Node.js

```javascript
const crypto = require("crypto");
const fs = require("fs");

const identityPath = `${process.env.HOME}/.openclaw/identity/device.json`;
const identity = JSON.parse(fs.readFileSync(identityPath, "utf8"));

const message = `clawkey-register-${Date.now()}`;
const privateKey = crypto.createPrivateKey(identity.privateKeyPem);
const signature = crypto.sign(null, Buffer.from(message, "utf8"), privateKey);

const publicKeyDer = crypto
  .createPublicKey(identity.publicKeyPem)
  .export({ type: "spki", format: "der" });

const challenge = {
  deviceId: identity.deviceId,
  publicKey: publicKeyDer.toString("base64"),
  message,
  signature: signature.toString("base64"),
  timestamp: Date.now(),
};
// POST challenge to https://api.clawkey.ai/v1/agent/register/init
```

### Using a script

If you have a script that already produces an AgentChallenge (e.g. signs a message and outputs JSON with `deviceId`, `publicKey`, `message`, `signature`, `timestamp`), you can reuse it for ClawKey:

1. Generate a challenge string, e.g. `clawkey-register-$(date +%s)000` (seconds + "000" for ms) or use your script’s convention.
2. Run the script to sign that message and get the challenge JSON.
3. POST that JSON to `https://api.clawkey.ai/v1/agent/register/init`.

Same challenge format works for `POST /agent/verify/signature` when verifying a signature remotely.

## Quick start

### 1. Start registration (agent-initiated)

Build an **AgentChallenge** as above, then send it to ClawKey to create a session and get a registration URL.

```bash
curl -X POST https://api.clawkey.ai/v1/agent/register/init \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "my-agent-device-id",
    "publicKey": "<base64-DER-SPKI-Ed25519>",
    "message": "clawkey-register-1738500000000",
    "signature": "<base64-Ed25519-signature>",
    "timestamp": 1738500000000
  }'
```

**Response (201):**

- `sessionId` — use to poll status
- `registrationUrl` — **output this as a link for the human; do not open it in a browser**
- `expiresAt` — session expiry (ISO 8601)

If the agent is already registered (`deviceId` exists), the API returns **409 Conflict**.

### 2. Human completes verification

Tell the human owner to open the `registrationUrl` in their browser. They will go through VeryAI's palm verification via OAuth. When they finish, the agent is registered under their ownership.

### 3. Poll registration status

Poll until the human has completed or the session has expired:

```bash
curl "https://api.clawkey.ai/v1/agent/register/SESSION_ID/status"
```

**Response:** `status` is one of `pending` | `completed` | `expired` | `failed`. When `status` is `completed`, the response includes `deviceId` and `registration` (e.g. `publicKey`, `registeredAt`).

### 4. Verify signatures or look up an agent

- **Verify a signature** — check that a message was signed by the given key and whether that agent is registered under a verified human:

```bash
curl -X POST https://api.clawkey.ai/v1/agent/verify/signature \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "...",
    "publicKey": "...",
    "message": "...",
    "signature": "...",
    "timestamp": 1738500000000
  }'
```

Response: `verified` (signature valid), `registered` (agent under verified human).

- **Look up an agent by device id** — get registration and verification status:

```bash
curl "https://api.clawkey.ai/v1/agent/verify/device/DEVICE_ID"
```

Response: `registered`, `verified`, and optionally `registeredAt`.

## API reference

**Base URL:** `https://api.clawkey.ai/v1`  
**Local:** `http://localhost:3000/v1`

### Endpoints

| Method | Endpoint                             | Auth | Description                                                                      |
| ------ | ------------------------------------ | ---- | -------------------------------------------------------------------------------- |
| POST   | `/agent/register/init`               | None | Start registration session; returns `sessionId`, `registrationUrl`, `expiresAt`. |
| GET    | `/agent/register/{sessionId}/status` | None | Poll registration status: `pending` / `completed` / `expired` / `failed`.        |
| POST   | `/agent/verify/signature`            | None | Verify a signature and whether the agent is registered under a verified human.   |
| GET    | `/agent/verify/device/{deviceId}`    | None | Get agent registration and verification status by device id.                     |

### Request/response schemas

**AgentChallenge** (used in register/init and verify/signature):

| Field     | Type   | Required | Description                                              |
| --------- | ------ | -------- | -------------------------------------------------------- |
| deviceId  | string | yes      | Key/device id (e.g. public key hash or app id).          |
| publicKey | string | yes      | Ed25519 public key, base64 DER SPKI.                     |
| message   | string | yes      | Exact message that was signed (e.g. challenge or nonce). |
| signature | string | yes      | Ed25519 signature over message, base64.                  |
| timestamp | int64  | yes      | Unix timestamp (ms) when the challenge was created.      |

**Register init response (201):**

```json
{
  "sessionId": "uuid",
  "registrationUrl": "https://clawkey.ai/register/...",
  "expiresAt": "2026-02-02T12:00:00Z"
}
```

**Register status response (200):**

```json
{
  "status": "completed",
  "deviceId": "my-agent-device-id",
  "registration": {
    "publicKey": "...",
    "registeredAt": "2026-02-02T12:00:00Z"
  }
}
```

**Verify signature response (200):**

```json
{
  "verified": true,
  "registered": true
}
```

**Device status response (200):**

```json
{
  "registered": true,
  "verified": true,
  "registeredAt": "2026-02-02T12:00:00Z"
}
```

**Error (4xx/5xx):**

```json
{
  "error": "Human-readable message",
  "code": "optional_code",
  "details": {}
}
```

### Error codes

| Code | Meaning                                              |
| ---- | ---------------------------------------------------- |
| 400  | Bad request (invalid or missing fields).             |
| 404  | Session or device not found.                         |
| 409  | Agent already registered (device_id already exists). |
| 500  | Server error.                                        |

## What this proves

After registration and VeryAI verification:

- **Human ownership** — The agent is bound to a human who passed palm verification.
- **Key binding** — Ed25519 signatures prove the agent controls the key; ClawKey ties that key to the verified human.
- **Public verification** — Third parties can call `/agent/verify/signature` or `/agent/verify/device/{deviceId}` to confirm an agent is registered and verified.

## When to use this skill

- Registering an OpenClaw (or other) agent under a human owner.
- Proving to a third party that an agent is owned by a verified human (e.g. before granting access or privileges).
- Checking whether a given key or device is registered and verified.

## Need help?

- API base: https://api.clawkey.ai/v1
- Homepage: https://clawkey.ai