IdentyClaw

IdentyClaw

Home API (default): https://api.identyclaw.com
Federated example: https://api-b.example.com (same Rodit login family; configure via apiEndpoints)

IdentyClaw is an HTTP API for IdentyClaw Passport holders and the HOLA mutual authentication protocol. This skill is a convenience cheat sheet for agents; tool catalog and install steps live in the plugin README. Deep specs live in bundled references/ and MCP doc:* resources.

Convenience document: Change the plugin README and MCP doc:* resources first; update this skill only to keep the walkthrough accurate.

Live docs: MCP doc:discovery · doc:skills · curl https://api.identyclaw.com/api/mcp/resource/doc:skills

ClawHub: identyclaw/identyclaw · OpenClaw plugin · Source (skill + plugin)

---

Home vs federated — do not assume shared routes

Federation shares Rodit login only (GET /api/login/timestamp → sign → POST /api/login → JWT cached per URL). A federated peer may expose any product routes. It does not inherit the home IdentyClaw surface (/api/me/identity, HOLA, DID, /api/agents, …).

Never probe home-only tools against a federated host “to see if they work.” A 404 on /api/me/identity is expected when that peer does not implement it — not a login failure.

---

Agent rule — do not hand-roll login

When the OpenClaw plugin is installed (identyclaw-tools):

1. Never curl GET /api/login/timestamp or POST /api/login, and never invent Ed25519 signatures in chat.
2. Call identyclaw_ensure_session (optional apiEndpoint) — the plugin auto-logins and caches a JWT per API URL.
3. Home tools stay on home: omit apiEndpoint for Passport/HOLA/DID helpers unless you already know that host implements those IdentyClaw paths.
4. Federated product work: after ensure_session, discover that peer’s routes, then call them with identyclaw_request — do not reuse home tool paths.
5. Use identyclaw_list_sessions to see which APIs already have a live session.
6. A2A P2P (message another agent over /a2a) is not this plugin — install/use identyclaw-a2a. That plugin owns per-peer JWTs.

Manual curl login below is for operators / non-plugin clients only.

---

Two lanes — do not mix them

Two clocks:

A JWT is not a HOLA line. HOLA tools need an API session to call protected routes; the handshake payload is the HOLA wire string.

---

Credentials (ClawHub “API key required” badge)

ClawHub’s badge means your IdentyClaw Passport — not a separate vendor API key.

nearPrivateKey on the Gateway — same NEAR key, two signatures:

1. API login — base64url over accountid + timestamp_iso
2. HOLA create — base32 over uppercase canonical HOLA prefix (identyclaw_create_hola / @rodit/hola-client)

identyclaw_verify_hola needs only API session + peer HOLA line (no nearPrivateKey).

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

Env alternative: IDENTYCLAW_API_ENDPOINTS=https://api-b.example.com.

Enroll first if needed: references/login-authentication.md. Never paste keys or JWTs into chat.

Security notes (operators):

• Prefer the OpenClaw plugin for login/HOLA so private keys and JWTs stay on the Gateway.
• Passport metadata (DN, ContactURI, geo, facial fields) is sensitive — minimize logging and collection.
• Agent-to-agent A2A is not this skill — use identyclaw-a2a / the A2A trust skill. Do not enable autonomous email from this skill’s docs.

---

Install and entry points

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

---

Agent cheat sheet

1. API session (plugin — preferred)

# Home identity / HOLA / DID
identyclaw_ensure_session
identyclaw_get_my_identity
identyclaw_list_sessions

# Federated peer — login + discover + product routes (arbitrary paths)
identyclaw_ensure_session   apiEndpoint=https://api-b.example.com
identyclaw_list_resources   apiEndpoint=https://api-b.example.com
identyclaw_get_resource     uri=doc:discovery  apiEndpoint=https://api-b.example.com
identyclaw_request          method=GET path=/…  apiEndpoint=https://api-b.example.com

Sessions are cached per URL. You can be logged into home and federated APIs at the same time. Federated login does not mean the peer implements home IdentyClaw routes.

1b. Manual API login (operators / non-plugin only)

BASE=https://api.identyclaw.com   # or federated peer URL

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:  +  (no separator) → base64url_signature

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

Full steps: references/login-authentication.md.

2. Create outbound HOLA line

Recommended: identyclaw_create_hola (plugin v1.4.0+) — API session fetches nonce; private key signs HOLA locally.

HOLA/////API.IDENTYCLAW.COM//

Outbound HOLA rules (agents):

• Signer / origin is always this agent's Passport ID — resolved from GET /api/me/identity.
• Call identyclaw_create_hola without tokenId, or call identyclaw_get_my_identity first if you need your ID for other steps.
• Never ask the user for your own Passport ID to create an outbound HOLA line.
• Only recipient may be user-supplied (peer Passport ID or MUNDO for broadcast intros).
• Subagent delegation uses a different HOLA wire format — see references/hola-subagent-authentication.md; do not substitute another agent's ID in standard outbound HOLA.

Walkthrough: references/hola-howto.md. Self-test: POST /api/testhola.

3. Verify an incoming HOLA line

Use identyclaw_verify_hola with the exact HOLA string. The JWT only authorizes the API call.

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

4–8. Identity, discovery, DID (home API)

Prefer plugin tools on the home baseUrl (identyclaw_get_agent_identity, identyclaw_list_agents, identyclaw_resolve_did). Only pass apiEndpoint when you already know that host implements the same IdentyClaw path.

---

First contact from an unknown agent

1. Home API session — identyclaw_ensure_session (do not curl login).
2. Verify HOLA line — identyclaw_verify_hola with the exact string received (not a JWT).
3. If verified: true — note peerTokenId.
4. Lookup — identyclaw_get_agent_identity (home).
5. Impersonation guard — compare peerTokenId to officially published Passport ID. references/finding-agents.md.
6. Subagent — identyclaw_check_subagent_signer when delegation fields present. references/hola-subagent-authentication.md.
7. Ongoing messaging — use A2A (identyclaw-a2a), not repeated HOLA for every turn.

---

OpenClaw plugin (recommended for Gateways)

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

Plugin v1.6.0+ · tool reference: README.md

Session tools

Discovery / generic HTTP (safe on federated peers)

Home IdentyClaw surface (default: omit apiEndpoint)

These home-surface tools still accept apiEndpoint for rare full IdentyClaw replicas — do not pass a federated product host unless you know it implements that path. Allowlist optional tools in tools.allow when credentials are configured. Enable idcp only when on-chain wallet actions are required (near on PATH).

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

---

Bundled references

---

Conventions

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

Skill vs plugin vs MCP vs A2A: This skill teaches workflows. The identyclaw-tools plugin runs multi-API login, HOLA, and identity. MCP serves documentation. identyclaw-a2a owns agent-to-agent P2P JWTs.