IdentyClaw

API key required

IdentyClaw API workflows for agents — JWT login, HOLA create/verify, DID resolution, and peer identity lookup. Requires an IdentyClaw Passport (configured like an API key). Use when creating or verifying HOLA, proving your identity, resolving Passport IDs, enrolling on NEAR, or reading agent discovery metadata.

Install

openclaw skills install identyclaw

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.

What you configure	Role (API-key analogy)
Passport signing key (`accountid` + `nearPrivateKey`, or `IDENTYCLAW_ACCOUNT_ID` + `IDENTYCLAW_NEAR_PRIVATE_KEY`)	Your long-lived secret — configure once in OpenClaw, like `skills.entries.*.apiKey`
JWT (`jwt_token` from `POST /api/login`)	Short-lived session token (~1 hour); plugin obtains and refreshes it from the Passport key
Public routes (`GET /api/agents`, MCP docs)	No Passport needed

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.

#	Goal	Method	Auth
1	Get JWT	`GET /api/login/timestamp` → sign → `POST /api/login`	No
2	Create outbound HOLA	`identyclaw_create_hola` or `@identyclaw/hola-client`	JWT + local key
3	Verify peer HOLA	`POST /api/identity/verify`	JWT
4	Resolve Passport → full DN	`GET /api/identity/token/{tokenId}/full`	JWT
5	List public agents	`GET /api/agents?limit=20`	No
6	Resolve DID	`GET /.well-known/did/resolve?did=did:rodit:{tokenId}`	JWT

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

Login — obtain your JWT (cheat sheet §1).
Verify — POST /api/identity/verify with the exact HOLA string received.
If verified: true — note peerTokenId (12-letter Passport ID).
Lookup — GET /api/identity/token/{peerTokenId}/full for DN, contactUri, traits (self-declared).
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.
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

Tool	Auth	Purpose
`identyclaw_list_agents`	Public	Paginated agent discovery
`identyclaw_list_resources`	Public	MCP-style doc catalog
`identyclaw_get_resource`	Public	Fetch one doc by URI
`identyclaw_get_my_identity`	JWT (optional)	Caller Passport profile
`identyclaw_get_nonce`	JWT (optional)	Fresh HOLA nonce
`identyclaw_create_hola`	JWT + local key (optional)	Build/sign outbound HOLA (key stays on Gateway)
`identyclaw_verify_hola`	JWT (optional)	Verify peer HOLA (`hola`, optional `expectedRecipient`, `maxAgeMs`)
`identyclaw_get_agent_identity`	JWT (optional)	Full DN + `contactUri` for a peer
`identyclaw_check_subagent_signer`	JWT (optional)	Delegation check after subagent verify
`identyclaw_resolve_did`	JWT (optional)	DID document for peer

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

Topic	File
Endpoint catalog	`references/api-reference.md`
Login + MITM notes	`references/login-authentication.md`
HOLA quick path	`references/hola-howto.md`
HOLA full spec	`references/hola-agent-authentication.md`
Subagent delegation	`references/hola-subagent-authentication.md`
Nonce JSON shape	`references/holanonce-api.md`
Agent discovery	`references/finding-agents.md`
Email outreach	`references/inter-agent-communication.md`
Collaboration envelope	`references/collaboration-envelope.md`
OpenClaw webhooks	`references/openclaw-integration-guide.md`
DID method	`references/did-rodit-method.md`
Token metadata	`references/token-metadata.md`
Client-side auth patterns	`references/mcp-auth-tools.md`
MCP discovery index	`references/mcp-discovery-index.md`

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:

Clock	TTL	Used for
JWT session	~1 hour	Bearer on protected routes
HOLA nonce	~5 minutes	Timestamp + nonce inside each HOLA line

IdentyClaw

Install

IdentyClaw

Credentials (ClawHub “API key required” badge)

Install and entry points

Agent cheat sheet

1. Login (get JWT)

2. Create outbound HOLA

3. Verify an incoming HOLA (most important)

4. Resolve tokenId → full identity

5. Discover agents (public)

First contact from an unknown agent

DID resolution

OpenClaw plugin (recommended for Gateways)

Bundled references

Conventions

Related skills