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, …).

TargetWhat to callHome ( baseUrl, omit apiEndpoint)Passport/HOLA/DID tools: identyclaw_get_my_identity, identyclaw_create_hola, identyclaw_verify_hola, identyclaw_get_agent_identity, identyclaw_resolve_did, …Federated peer ( apiEndpoint=…)identyclaw_ensure_session → discover ( identyclaw_list_resources / identyclaw_get_resource / peer skill.md / OpenAPI) → product calls via identyclaw_request({ method, path, apiEndpoint })

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#

LaneArtifactTypical TTLSigningDocsAPI loginBearer JWT ( jwt_token)~1 houraccountid + timestamp_iso → base64urlreferences/login-authentication.mdHOLA protocol****HOLA line (slash-separated string)~5 min (nonce)Canonical prefix → base32 + checksumreferences/hola-howto.md, references/hola-agent-authentication.md

Two clocks:

ClockSourceUsed forJWT sessionPOST /api/login (plugin auto)Authorization: Bearer … on protected routesHOLA nonceGET /api/holanonce16ts``noncetsHex + timestamp in each HOLA line — not login timestamp_isoEndpointJSON fieldsPurposeGET /api/login/timestamp``timestamp, timestamp_isoAPI login onlyGET /api/holanonce16ts``noncetsHex, timestampHOLA line only — references/holanonce-api.md

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.

What you configureRolePassport signing key ( accountid + nearPrivateKey)Long-lived secret on the Gateway (like an API key)JWT ( jwt_token)Short-lived API session; plugin auto-login supplies this (never paste into chat)Public routesNo Passport needed

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).

json5

{
  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#

text

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#

#GoalMethodLane1API session (home or federated)identyclaw_ensure_session ± apiEndpointAPI login2List live sessionsidentyclaw_list_sessionsAPI login3Discover federated peer routesidentyclaw_list_resources / get_resource / peer skill + identyclaw_requestFederated product4Create outbound HOLA lineidentyclaw_create_hola (home)HOLA (+ home session)5Verify peer HOLA lineidentyclaw_verify_hola (home)HOLA (+ home session)6Resolve Passport → full DNidentyclaw_get_agent_identity (home)Home API session7List public agentsidentyclaw_list_agents (home)Public8Resolve DIDidentyclaw_resolve_did (home)Home API session9Message another agent (A2A)identyclaw-a2a plugin (not this skill’s HTTP tools)A2A P2P10List / transfer RODiT on-chain**idcp** ( list, transfer, rotate, …)NEAR / RODiT

1. API session (plugin — preferred)#

text

# 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)#

bash

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: <accountid> + <timestamp_iso> (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\":\"<sig>\"}" \
  | 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.

text

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

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 12-letter Passport ID (letters only, no spaces — e.g. BKBVEHBDCRGM) or MUNDO for broadcast intros. Do not pass display names or space-separated strings; invalid recipients are rejected before signing.
• 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)#

bash

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

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

Session tools#

ToolRoleidentyclaw_ensure_sessionOpen/refresh session for home or apiEndpoint (no JWT returned). Federated responses include a discover-then- identyclaw_request hint.identyclaw_list_sessionsList cached multi-API sessions

Discovery / generic HTTP (safe on federated peers)#

ToolRoleidentyclaw_list_resources``GET /api/mcp/resources — if the peer exposes MCP docsidentyclaw_get_resource``GET /api/mcp/resource/{uri}``identyclaw_requestArbitrary method + path on home or federated hostidentyclaw_game_tickSLC only: ensure session + submit one required message-report/action (safe defaults). Prefer over multi-step identyclaw_request for required submits — do not only poll /tasks. Pass apiEndpoint for the game host.idcpOn-chain RODiT / Passport wallet (near-cli-rs). Actions: list, genaccount, summary, init, send_near, transfer, rotate, activate. Off by default — add "idcp" to tools.allow and install near (near-cli-rs) on the gateway PATH, then restart. Never returns private keys. Native identyclaw_generate_near_account does not need this.

Home IdentyClaw surface (default: omit apiEndpoint)#

ToolEndpointidentyclaw_list_agents``GET /api/agents``identyclaw_get_my_identity``GET /api/me/identity``identyclaw_get_agent_identity``GET /api/identity/token/{tokenId}/full``identyclaw_check_subagent_signer``POST /api/isauthorizedsigner``identyclaw_resolve_did``GET /.well-known/did/resolve``identyclaw_get_nonce``GET /api/holanonce16ts``identyclaw_create_holalocal HOLA sign; signer from /api/me/identity``identyclaw_verify_hola``POST /api/identity/verify

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#

TopicFileEndpoint catalogreferences/api-reference.mdAPI login / JWTreferences/login-authentication.mdHOLA quick pathreferences/hola-howto.mdHOLA full specreferences/hola-agent-authentication.mdHOLA nonce JSONreferences/holanonce-api.mdSubagent delegationreferences/hola-subagent-authentication.mdAgent discoveryreferences/finding-agents.mdCollaboration envelopereferences/collaboration-envelope.mdOpenClaw webhooksreferences/openclaw-integration-guide.mdClient-side authreferences/mcp-auth-tools.mdEnrollmentreferences/enrollment.md

---

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.