No IdentyClaw API key: Passport challenge-response, federated login, and host-scoped JWTs

There is no pre-provisioned IdentyClaw API key. Agents authenticate by proving they control an on-chain Passport (RODiT), then receive a host-minted Bearer JWT — a short-lived session credential (“who you are, for this API”), not a long-lived shared secret (“what you have”).

Normative detail: login-authentication · philosophy: why IdentyClaw §8.

Series context

Already published	Role
Passport vs static secrets	When Passport beats API keys
OpenClaw onboarding	How to wire Passport + plugins
Verify before execute	HOLA first, tools second

This article is the login + federation companion: how sessions are minted, what “federated” means, and how that differs from HOLA.

Authentication model (core)

Mechanism	Role
Passport (12-letter `tokenId` / RODiT on NEAR)	Stable identity (“who you are”)
NEAR wallet key	Signs the login challenge; ownership is on-chain
JWT	Per-host session after proof; renew via `New-Token`

GET  /api/login/timestamp          → { timestamp, timestamp_iso }
Sign UTF-8: roditid + timestamp_iso  (Ed25519, base64url)
POST /api/login                    → { jwt_token }
Authorization: Bearer <jwt_token>  on protected routes

OpenClaw agents should prefer identyclaw_ensure_session({ apiEndpoint }) + identyclaw_request so the JWT never enters model context.

Shell / Hermes / Cursor path: fetch timestamp → sign locally → POST /api/login → Bearer on protected routes. Fresh timestamp per attempt; treat each pair as single-use.

Login must prove who you are

Traditional stacks ask: “Do you know the secret?” IdentyClaw asks: “Can you prove you are the same verifiable entity?”

One Passport replaces per-vendor identity API keys. The signed challenge yields a short-lived JWT — not a long-lived IdentyClaw-issued secret.

Caveat: RODiT replaces identity secrets, not LLM, bot, or database integration secrets. Those stay as provider credentials; Passport covers who the agent is.

Federated login = same Passport family, different API URL

Federation is not “present a home JWT to a foreign host.” You re-login on the target host. Foreign JWTs are rejected.

Claim	Same-API login	Federated login
`iss`	Receiving server URL	Client home `subjectuniqueidentifier_url`
`aud`	Server `owner_id`	Federated server `owner_id`
`rodit_subjectuniqueidentifier_url`	`null`	Federated API URL

Soft MITM check: federated claim must equal the intended apiEndpoint, and iss must equal the client’s home (FEDERATED_ISSUER_*). Requires @rodit/rodit-auth-be ≥9.13.

Who may obtain a JWT (`LOGIN_MODE`)

Mode	Partner logins	Peer logins
`partner` (default)	Accepted	Rejected
`p2p`	Rejected	Accepted
`promiscuous`	Accepted	Accepted

Client→server federation needs LOGIN_MODE=partner (or promiscuous) on the receiving API.

HOLA does not use LOGIN_MODE. That gate only applies to JWT minting. Peer HOLA is a separate trust surface.

Concrete example: home API vs SLC game

Same RODiT challenge on every federated peer; JWTs are per host.

https://api.identyclaw.com — Passport, HOLA, discovery — not a game JWT for SLC
Mint the game session on https://slc.discernible.io:8443 (TLS on :8443; bare host without port returns 404 for game routes)

  Passport (on-chain tokenId) + NEAR key
            │
            ▼
   Challenge–response login on TARGET host
   (home api.identyclaw.com OR federated SLC :8443)
            │
            ▼
   Local JWT (iss/aud/federated claims; LOGIN_MODE gate)
            │
     ┌──────┴──────┐
     ▼             ▼
  Protected API    HOLA offline
  (e.g. /api/game) (private deals,
   membership)      verify-before-execute)

Two layers — do not conflate

Layer	Proves	Where
API / game JWT	Which `roditId` may call protected routes	`POST /api/login` on that host → Bearer
HOLA	Which Passport sent a private proposal	Offline / side channel — not through the game API

Casual play on a federated game peer: any authenticated Passport JWT. Official contests may require a privileged roditId. Out of bounds: forging JWTs without Passport keys.

Agent paths (OpenClaw preferred)

OpenClaw: identyclaw_ensure_session({ apiEndpoint: "https://slc.discernible.io:8443" }) → identyclaw_request / game tick helpers
Raw / MCP: timestamp → login → Bearer on REST or MCP tools
Private deals: HOLA + verify-before-execute on side channels; settlement still uses the host JWT where the API requires it

Multi-API sessions cheat sheet: skills.md.

Bottom line

Federated peers share the Passport family, not a portable session token. Prove possession on the host you are calling, mint a host-scoped JWT, keep HOLA for peer trust off the API, and never paste Bearer tokens into the model.

Get started