IdentyClaw

Base URL: https://api.identyclaw.com

IdentyClaw is an HTTP API for IdentyClaw Passport holders and the HOLA mutual authentication protocol. Most agent work needs a JWT (login) and POST /api/identity/verify (validate any inbound HOLA in one call). Deep protocol detail lives in bundled references/; this file is the runnable cheat sheet.

Live docs: MCP doc:discovery (index) · doc:skills (cheat sheet) · curl https://api.identyclaw.com/api/mcp/resource/doc:skills

ClawHub (published): identyclaw/identyclaw · OpenClaw plugin

Credentials (ClawHub “API key required” badge)

ClawHub shows a generic API key required badge when a skill needs a user-supplied credential. For IdentyClaw, that credential is your IdentyClaw Passport — not a separate vendor API key.

OpenClaw setup (recommended): put Passport material in plugin config — never paste keys into chat:

{
  plugins: {
    entries: {
      "identyclaw-tools": {
        enabled: true,
        config: {
          baseUrl: "https://api.identyclaw.com",
          accountid: "<64-char-hex-near-implicit-account>",
          nearPrivateKey: "ed25519:..."
        }
      }
    }
  }
}

Enroll or mint a Passport first if you do not have one — see references/login-authentication.md. HOLA signing always uses your Passport key locally; the API never holds it.

Install and entry points

Skill (workflows):     openclaw skills install clawhub:identyclaw
Plugin (tools):        openclaw plugins install clawhub:@identyclaw/openclaw-identyclaw-plugin
MCP (docs):            https://api.identyclaw.com/mcp
Discovery index:       doc:discovery
Cheat sheet:           doc:skills

Agent cheat sheet

Protected routes need Authorization: Bearer <jwt_token> from POST /api/login. Field name is jwt_token. JWT lasts ~1 hour; HOLA nonces last ~5 minutes — fetch a new nonce immediately before each HOLA you sign.

1. Login (get JWT)

BASE=https://api.identyclaw.com

TS_JSON=$(curl -sS "$BASE/api/login/timestamp")
TIMESTAMP=$(echo "$TS_JSON" | jq -r '.timestamp')
TIMESTAMP_ISO=$(echo "$TS_JSON" | jq -r '.timestamp_iso')

# Sign UTF-8 bytes of: <accountid> + <timestamp_iso> (no separator)
# → base64url_signature with your NEAR/Passport Ed25519 key

JWT=$(curl -sS -X POST "$BASE/api/login" \
  -H "Content-Type: application/json" \
  -d "{\"accountid\":\"<64-char-hex>\",\"timestamp\":$TIMESTAMP,\"base64url_signature\":\"<sig>\"}" \
  | jq -r '.jwt_token')

Full signing steps: references/login-authentication.md.

2. Create outbound HOLA

Recommended: OpenClaw identyclaw_create_hola (plugin v1.3.0+) or @identyclaw/hola-client — JWT fetches nonce; private key signs locally (never sent to API).

Manual fallback: GET /api/holanonce16ts → sign uppercase canonical line → POST /api/testhola to self-test.

HOLA/<recipient>/<tokenId>/<timestamp>/<noncetsHex>/API.IDENTYCLAW.COM/<base32-signature>/<checksum>

Walkthrough: references/hola-howto.md. Spec: references/hola-agent-authentication.md.

3. Verify an incoming HOLA (most important)

One call validates format, checksum, freshness, nonce replay, token existence/active, and on-chain signature. Do not trust local crypto alone — wait for verified: true.

curl -sS -X POST https://api.identyclaw.com/api/identity/verify \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"hola":"HOLA/MUNDO/<peerTokenId>/...","expectedRecipient":"MUNDO"}'

Optional: expectedRecipient suppresses RECIPIENT_MISMATCH; constraints.maxAgeMs sets freshness window. Same fields on /api/testhola.

Trust only when verified: true. Diagnostics: references/hola-agent-authentication.md.

4. Resolve tokenId → full identity

curl -sS "https://api.identyclaw.com/api/identity/token/<tokenId>/full" \
  -H "Authorization: Bearer $JWT"

Public browse (no JWT): GET /api/agents?limit=20&cursor=... — then use /full per candidate. Patterns: references/finding-agents.md.

5. Discover agents (public)

curl -sS "https://api.identyclaw.com/api/agents?limit=20"

First contact from an unknown agent

1. Login — obtain your JWT (cheat sheet §1).
2. Verify — POST /api/identity/verify with the exact HOLA string received.
3. If verified: true — note peerTokenId (12-letter Passport ID).
4. Lookup — GET /api/identity/token/{peerTokenId}/full for DN, contactUri, traits (self-declared).
5. Impersonation guard — compare peerTokenId to the Passport ID the entity officially publishes on channels they control. If the verified peerTokenId is not the same ID the entity officially publishes, reject them as that entity, even though HOLA verification succeeded. See references/finding-agents.md.
6. Subagent only — if the line includes delegation fields, also call POST /api/isauthorizedsigner. See references/hola-subagent-authentication.md.

VERIFY=$(curl -sS -X POST "$BASE/api/identity/verify" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg h "$PEER_HOLA" '{hola:$h}')")

if [ "$(echo "$VERIFY" | jq -r '.verified')" = "true" ]; then
  TOKEN=$(echo "$VERIFY" | jq -r '.peerTokenId')
  curl -sS "$BASE/api/identity/token/$TOKEN/full" -H "Authorization: Bearer $JWT"
fi

DID resolution

curl -sS "https://api.identyclaw.com/.well-known/did/resolve?did=did:rodit:<tokenId>" \
  -H "Authorization: Bearer $JWT"

Spec: references/did-rodit-method.md.

OpenClaw plugin (recommended for Gateways)

Install the matching plugin so the agent calls typed tools instead of hand-rolled curl on every turn:

openclaw plugins install clawhub:@identyclaw/openclaw-identyclaw-plugin

Configure baseUrl, accountid, and nearPrivateKey under plugins.entries.identyclaw-tools.config. Enable optional tools in tools.allow when credentials are configured. Plugin v1.3.0+ required for identyclaw_create_hola.

ClawHub skill (this bundle): openclaw skills install clawhub:identyclaw

Bundled references

Conventions

Terminology: User-facing copy says IdentyClaw Passport (12-letter ID). RODiT is the underlying protocol technology only — do not say "RODiT Passport."

Two clocks: