Integration
Identyclaw
By OpenClaw plugin — IdentyClaw API login, HOLA, identity, and DID tools
Install
npm install
npmREADME
# IdentyClaw Tools Gateway Component
**OpenClaw plugin — IdentyClaw API login, HOLA, identity, and DID tools**
[IdentyClaw](https://www.discernible.io/#developers) — portable cryptographic identity for AI agents. Mint a Passport on NEAR, prove yourself with HOLA, and use the IdentyClaw API when you need it.
> **IdentyClaw component service:** OpenClaw plugin that exposes the IdentyClaw HTTP API as agent tools — discovery, Passport identity, **API session login**, **HOLA** create/verify, subagent delegation, DID resolution, and MCP-style documentation resources. API login and HOLA flows follow the live API contract (via vendored [`@rodit/hola-client`](./hola-client/) for HOLA signing). Protocol docs: [MCP discovery](https://api.identyclaw.com/.well-known/mcp) · [OpenAPI](https://api.identyclaw.com/swagger.json) · [`doc:reference:openclaw-integration-guide`](https://api.identyclaw.com/api/mcp/resource/doc:reference:openclaw-integration-guide).
[](https://www.npmjs.com/package/@identyclaw/openclaw-identyclaw-plugin) [](https://clawhub.ai/plugins/@identyclaw/openclaw-identyclaw-plugin) [](https://github.com/discernible-io/openclaw-identyclaw-plugin) [](https://github.com/discernible-io/openclaw-identyclaw-plugin/blob/main/LICENSE) [](https://api.identyclaw.com/api/mcp/resource/doc:reference:hola-authentication) [](https://api.identyclaw.com/.well-known/mcp)
> [!IMPORTANT]
> **Production deploy:** For nginx TLS, A2A peer messaging, signed webhooks, and GitHub Actions CI, use **[identyclaw-agents](https://github.com/discernible-io/identyclaw-agents)** instead of wiring plugins manually on the gateway host.
<p align="center">
<img src="images/identyclaw-tools-ecosystem.svg" alt="IdentyClaw stack: OpenClaw gateway, this tools component, and the IdentyClaw API" width="960"/>
</p>
## Quick start
Four steps to go from zero to a Passport-enrolled gateway (à la carte install — see the production callout above for the full stack template):
```bash
openclaw plugins install clawhub:@identyclaw/openclaw-identyclaw-plugin
openclaw gateway restart
identyclaw-generate-near-account
```
Purchase a Passport at [purchase.identyclaw.com](https://purchase.identyclaw.com) for the printed `implicit_account_id`, then restart the gateway so bootstrap syncs `IDENTYCLAW_*` into plugin config. On first startup with no credentials yet, the plugin can also auto-generate a NEAR account (ClawHub-safe — OpenClaw skips npm lifecycle scripts).
Details: [Installation](#-installation) · [NEAR account generation](#-near-account-generation-v150) · [Configuration](#-configuration) · [Tools](#-tools)
## Role in the IdentyClaw stack
| Layer | Artifact | Responsibility |
| --- | --- | --- |
| **Identity & HOLA (this repo)** | **`identyclaw-tools`** | API login, DID, HOLA create/verify, identity lookup, MCP resource tools |
| Passport API | [api.identyclaw.com](https://api.identyclaw.com/.well-known/mcp) | JWT issuance contract, `POST /api/login`, HOLA verify, token metadata — [OpenAPI](https://api.identyclaw.com/swagger.json) |
| A2A wire protocol | [`openclaw-a2a-idc-plugin`](https://github.com/discernible-io/openclaw-a2a-idc-plugin) | Agent Card discovery, `POST /a2a`, inbound JWT validation, outbound P2P login |
| Agent runtime | [OpenClaw](https://openclaw.ai) gateway | Chat, hooks, sandbox, tool execution |
Install this plugin when Passport-authenticated agents need **IdentyClaw API login, HOLA peer trust, identity discovery, or DID resolution** — not for A2A peer messaging (use `identyclaw-a2a` for that). NEAR Passport credentials use the [gennearaccount](https://github.com/discernible-io/gennearaccount) JSON layout under `secrets/near-credentials/` — same as [identyclaw-agents](https://github.com/discernible-io/identyclaw-agents) bootstrap.
Your agent gets `identyclaw_*` tools for IdentyClaw HTTP without hand-rolling login signatures or HOLA lines:
- `identyclaw_list_agents` / `identyclaw_list_resources` / `identyclaw_get_resource` for public discovery and MCP docs
- `identyclaw_get_my_identity` / `identyclaw_get_agent_identity` / `identyclaw_resolve_did` for Passport identity
- `identyclaw_get_nonce` / `identyclaw_create_hola` / `identyclaw_verify_hola` for HOLA peer authentication
- `identyclaw_check_subagent_signer` for delegation authorization checks
- `identyclaw_generate_near_account` (optional) for operator NEAR account creation on the gateway host
The plugin **auto-logins** when protected tools run: `GET /api/login/timestamp` → sign login payload → `POST /api/login` → cache `jwt_token` until near expiry; applies `New-Token` response headers when present.
## 📦 Installation
From ClawHub:
```bash
openclaw plugins install clawhub:@identyclaw/openclaw-identyclaw-plugin
```
From npm:
```bash
openclaw plugins install @identyclaw/openclaw-identyclaw-plugin
```
Local checkout (after `npm run prepare:publish`):
```bash
openclaw plugins install /path/to/openclaw-identyclaw-plugin
```
Restart the gateway:
```bash
openclaw gateway restart
```
Enable optional tools in OpenClaw config (see [Configuration](#-configuration) and [Tools](#-tools)):
```json5
{
plugins: {
entries: {
"identyclaw-tools": {
enabled: true,
config: {
baseUrl: "https://api.identyclaw.com",
accountid: "<64-char-hex-near-implicit-account>",
nearPrivateKey: "ed25519:..."
}
}
}
},
tools: {
allow: [
"identyclaw_get_my_identity",
"identyclaw_get_nonce",
"identyclaw_create_hola",
"identyclaw_verify_hola",
"identyclaw_get_agent_identity",
"identyclaw_check_subagent_signer",
"identyclaw_resolve_did"
]
}
}
```
### Related IdentyClaw artifacts
| Artifact | Install / link | Role |
| --- | --- | --- |
| **This plugin** (`identyclaw-tools`) | `openclaw plugins install clawhub:@identyclaw/openclaw-identyclaw-plugin` | API login, HOLA, identity, DID, MCP resource tools |
| API contract (MCP) | [api.identyclaw.com/.well-known/mcp](https://api.identyclaw.com/.well-known/mcp) | Canonical JWT, HOLA, and API docs — fetch via `identyclaw_get_resource` or curl |
| A2A component | `openclaw plugins install clawhub:@identyclaw/openclaw-a2a-plugin` | A2A send/receive — [`openclaw-a2a-idc-plugin`](https://github.com/discernible-io/openclaw-a2a-idc-plugin) |
| NEAR credentials layout | [gennearaccount](https://github.com/discernible-io/gennearaccount) · [identyclaw-agents](https://github.com/discernible-io/identyclaw-agents) `secrets/near-credentials/` | Implicit-account JSON written by CLI, plugin, or C tool |
| Skill (workflows) | `openclaw skills install clawhub:identyclaw` | Operator playbooks — [`skill/SKILL.md`](./skill/SKILL.md) in this repo |
| MCP (canonical docs) | `https://api.identyclaw.com/mcp` | Live IdentyClaw API documentation |
`identyclaw-tools` and `identyclaw-a2a` can share `IDENTYCLAW_ACCOUNT_ID`, `IDENTYCLAW_NEAR_PRIVATE_KEY`, and `IDENTYCLAW_BASE_URL`. HOLA stays application-layer via `identyclaw_*` tools; A2A peer calls use Passport JWTs through the A2A component.
## 🔐 Two lanes — do not mix them
IdentyClaw uses **two separate authentication mechanisms**. This plugin implements both, but they are not interchangeable. Vocabulary: [`doc:reference:login-authentication`](https://api.identyclaw.com/api/mcp/resource/doc:reference:login-authentication) vs [`doc:reference:hola-authentication`](https://api.identyclaw.com/api/mcp/resource/doc:reference:hola-authentication).
| Lane | Artifact | Typical TTL | Signed payload | IdentyClaw docs |
| --- | --- | --- | --- | --- |
| **API login** | Bearer **JWT** (`jwt_token` from `POST /api/login`) | ~1 hour | `accountid` + `timestamp_iso` → **base64url** Ed25519 signature | [`doc:reference:login-authentication`](https://api.identyclaw.com/api/mcp/resource/doc:reference:login-authentication) |
| **HOLA protocol** | **HOLA line** (slash-separated wire string) | ~5 min (nonce freshness) | Uppercase canonical prefix → **base32** Ed25519 signature + checksum | [`doc:reference:hola-authentication`](https://api.identyclaw.com/api/mcp/resource/doc:reference:hola-authentication), [`doc:reference:hola-howto`](https://api.identyclaw.com/api/mcp/resource/doc:reference:hola-howto) |
**Two clocks** (from [`doc:reference:hola-howto`](https://api.identyclaw.com/api/mcp/resource/doc:reference:hola-howto)):
| Clock | Source | Used for |
| --- | --- | --- |
| JWT **session** | `POST /api/login` | `Authorization: Bearer …` on protected API routes |
| HOLA **nonce** | `GET /api/holanonce16ts` | `noncetsHex` + `timestamp` inside each HOLA line — **not** login `timestamp_iso` |
A JWT is **not** a HOLA line. HOLA tools need an API session only so the plugin can call protected endpoints (`/api/holanonce16ts`, `/api/identity/verify`, …). The peer handshake itself is the **HOLA line** you send or verify.
**Timestamp endpoints are different:**
| Endpoint | JSON fields | Purpose |
| --- | --- | --- |
| `GET /api/login/timestamp` | `timestamp`, `timestamp_iso` | API login signing only |
| `GET /api/holanonce16ts` | `noncetsHex`, `timestamp` | HOLA line construction only — see [`doc:reference:holanonce-api`](https://api.identyclaw.com/api/mcp/resource/doc:reference:holanonce-api) |
### `nearPrivateKey` on the Gateway host
The same NEAR key signs **two different messages** (different encodings):
1. **API login** — UTF-8 `accountid` + `timestamp_iso` → **base64url** signature on `POST /api/login`.
2. *
... (truncated)
integration
Comments
Sign in to leave a comment