mirror of https://github.com/hanzo-apps/hanzo.ai.git synced 2026-10-29 07:20:43 +00:00

Files

T

zeekay 992a1a3a18 auth.md: the text hanzoskills.com serves

Bare URLs (a scanner fetched a code span's closing backtick as part of
one) and no protocol token in the section on what is not implemented (a
scanner scored the names as support).

2026-10-26 21:01:15 -07:00

4.2 KiB

Raw Permalink Blame History

auth.md

You are an agent that needs a credential for the Hanzo API. Registration here is wallet sign-in, or a device code a person approves: discover, register, exchange the code for an access_token, mint an API key, call the API, revoke. The resource server is https://api.hanzo.ai (REST under /v1, MCP at /v1/mcp). The authorization server is https://hanzo.id (OpenID Connect). Every step is one HTTPS request.

Summary

Audience: AI agents, acting for themselves or for a person.
Registration endpoint: POST https://hanzo.id/v1/iam/web3/verify registers a first-seen wallet (its own account and organization) and returns an authorization code.
Supported methods: wallet sign-in (a CAIP-122 message signed with EIP-191) and device authorization (RFC 8628, a person approves).
Token endpoint: POST https://hanzo.id/v1/iam/oauth/token returns the access_token.
Credential: the Bearer access_token (seven days), or an API key from POST https://api.hanzo.ai/v1/account/keys, sent as Authorization: Bearer.

Step 1: Discover

GET https://api.hanzo.ai/.well-known/oauth-protected-resource (RFC 9728) answers resource: https://api.hanzo.ai, authorization_servers: ["https://hanzo.id"], bearer_methods_supported: ["header"].
GET https://hanzo.id/.well-known/openid-configuration answers issuer: https://hanzo.id, token_endpoint: https://hanzo.id/v1/iam/oauth/token, PKCE S256.

Step 2: Pick a method

No person available: register with a wallet.
A person can approve on any device: the device flow.
A person already holds a key: they mint one at https://platform.hanzo.ai under API keys.

Step 3: Register

Wallet, no person

GET https://hanzo.id/v1/iam/web3/nonce?chain=evm&address=0x… returns a challenge (domain, uri, statement, nonce, issuedAt, expirationTime, version). It lives 10 minutes.
Build the CAIP-122 message from it and sign it with EIP-191 personal_sign.
POST https://hanzo.id/v1/iam/web3/verify with {"clientId":"hanzo-ai","chain":"evm","scheme":"secp256k1-eip191","address":"0x…","message":"…","signature":"0x…","type":"code","redirectUri":"http://localhost:3000/callback","scope":"openid profile email","codeChallenge":"<S256>","codeChallengeMethod":"S256"} returns an authorization code. A first-seen wallet is registered: it gets its own account and organization, on the Free plan.

The whole flow as one TypeScript file, run end to end: https://hanzoskills.com/hanzo.md

Device, a person approves

POST https://hanzo.id/v1/iam/oauth/device?client_id=hanzo-cli&scope=openid%20profile%20email&response_type=device_code returns device_code, user_code, verification_uri_complete, expires_in 900, interval 5.
Show the person verification_uri_complete; they approve on any device.

The CLI does the same: curl -fsSL https://hanzo.sh | sh, then hanzo auth login.

Step 4: Exchange for an access_token

POST https://hanzo.id/v1/iam/oauth/token (form encoded):

Wallet: grant_type=authorization_code, client_id=hanzo-ai, code, code_verifier, redirect_uri. The Bearer access_token is valid seven days (expires_in 604800).
Device: grant_type=urn:ietf:params:oauth:grant-type:device_code, client_id=hanzo-cli, device_code, every 5 seconds until the person approves.

Step 5: Mint an API key

POST https://api.hanzo.ai/v1/account/keys with the access_token and {"name":"agent","type":"secret"} returns key (sk-live-…), shown once. It outlives the access_token. Keep it in a secret store, never in a tracked file. No card is needed.

Step 6: Use the access_token or key

Send Authorization: Bearer <key or access_token> to the REST API under https://api.hanzo.ai/v1 and to the MCP endpoint https://api.hanzo.ai/v1/mcp (protocol revision 2026-07-28).

Revocation

GET https://api.hanzo.ai/v1/account/keys lists your keys; DELETE https://api.hanzo.ai/v1/account/keys/{id} revokes one, and a request inside the next 60 seconds may still be served. Whoever holds the wallet key can sign in as that account: guard it like the API key.

Not implemented

The auth.md agent-registration protocol is not implemented here: there is no agent identity endpoint, no identity assertion exchange and no claim ceremony. Use one of the methods above.

4.2 KiB Raw Permalink Blame History