POST /v1/agents/{agentId}/open

Authentication

Send an API key as a bearer token. The endpoint checks agents.login.reveal, agents.view; a key without it is refused with 403, not 404.

This endpoint takes no organisation id. Your key already identifies the organisation it belongs to, and the response is scoped to it.

Try it

Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.

curl -X POST https://api.zinndigital.com/v1/agents/{agentId}/open \
  -H "Authorization: Bearer zdk_live_…"

Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console

Details

Every *.zinnagents.com request passes our sign-in check before it can reach the agent's pod (docs/1047 §12): only the OWNER of the agent's organisation gets through (agents.login.reveal; not dev, not any read role, not an owner of another organisation), and everyone else gets 401/403 from the check. This call returns url — https://<agent>/_zinn/open?t=<ticket> — where the ticket is signed, bound to this agent, its organisation, the caller and the agent's host, valid for expires_in seconds and redeemable ONCE. Redeeming it audit-logs agent.edge_login, sets a host-only session cookie on the agent's host and redirects to the app, already signed in: OpenClaw runs in trusted-proxy mode with device auto-approval (no token, no pairing step) and Hermes receives its basic-auth credentials from the check. The session is re-checked on every request, so a removed owner or a paused agent loses access within seconds. Session users only (an API key gets 404). Refused with 409 LOGIN_PAUSED while the agent is paused and 402 LOGIN_UNPAID while its plan is not in good standing. A POST, no-store.

Parameters

Response

Errors this endpoint can return

401 · 402 · 403 · 404 · 409