Authentication

Every Agent authenticates with a single credential: its Agent API key.

The SDK uses it to open the connection to the platform and to make every resource call your handler needs during a Run. If you're building your own SDK, this page is the authentication contract.

Agent API keys

An Agent API key identifies exactly one Agent.

• Create it in the dashboard under Developer → Agents → your Agent → API Keys.
• The raw key is shown once — copy it immediately. Keys look like z3t_agentkey_....
• Rotate or revoke keys from the same panel at any time.

Store the key as an environment variable and pass it to the SDK — never commit it.

export Z3T_AGENT_KEY="z3t_agentkey_..."

const agent = new Agent({ apiKey: process.env.Z3T_AGENT_KEY! })

One host

Every HTTP request your Agent makes goes to a single host:

https://relay.z3t.ai/v1

This is the default baseUrl. Bootstrap, schema sync, and every resource call your handler makes all route through it — you don't construct per-service hostnames.

Bearer authentication

Authentication is a standard bearer token: your Agent key.

On startup, the SDK discovers the platform's relays:

GET https://relay.z3t.ai/v1/bootstrap
Authorization: Bearer {apiKey}

200 { "relayUrls": ["wss://...", "wss://..."] }

It then opens a persistent WebSocket to each relay and authenticates on the connection itself:

{ "type": "auth", "apiKey": "...", "supportedVersions": [1, 2] }

The relay replies with auth_ok (carrying your agentId). If auth is rejected, the SDK treats it like a dropped connection and retries with backoff.

Authenticating resource calls

During a Run, your handler reaches platform resources (files, taxonomies, integrations, other Agents) over HTTP. Every one of those requests carries two headers:

Authorization: Bearer {apiKey}
x-agent-call-id: {callId}

The x-agent-call-id header ties each request to the Run that made it, so platform usage — including LLM calls made through ctx.llm — is attributed to the right call.

The storage exception

File uploads and downloads use short-lived presigned storage URLs.

Those two requests go directly to the storage host and carry no Authorization header — the signed URL itself is the credential. Every other request uses the bearer key above.

---

Continue learning

API

SDK Reference

For creators