Quick Start

This guide gets a local ZeroID instance running, registers an agent, and issues a short-lived access token you can use against downstream systems.

The examples below assume you are working from the open source zeroid repository and using the Highflame SDK integration for client-side calls.

Prerequisites

• Docker and Docker Compose

• openssl

• Python 3.10+ if you want to use the Python SDK example

• Node.js 18+ if you want to use the TypeScript SDK example

Step 1: Start ZeroID Locally

From the zeroid repository:

make setup-keys
docker compose up -d
curl http://localhost:8899/health

Expected response:

{
  "status": "healthy",
  "service": "zeroid"
}

The local stack uses:

• http://localhost:8899 for the ZeroID server

• PostgreSQL behind Docker Compose

• ECDSA and RSA signing keys from ./keys/

Step 2: Install an SDK

Python:

pip install highflame cryptography PyJWT

TypeScript:

npm install highflame

Step 3: Create a Client

Python:

from highflame.zeroid import ZeroIDClient

client = ZeroIDClient(base_url="http://localhost:8899")

print(client.account_id)
print(client.project_id)

TypeScript:

import { ZeroIDClient } from "highflame";

const client = new ZeroIDClient({
  baseUrl: "http://localhost:8899",
});

console.log(client.accountId);
console.log(client.projectId);

For local development, both SDKs can auto-generate tenant IDs if you do not provide them. In production, pass explicit account_id and project_id values.

Step 4: Register an Agent

Python:

registered = client.agents.register(
    name="Billing Orchestrator",
    external_id="billing-orchestrator",
    sub_type="orchestrator",
    trust_level="first_party",
    created_by="[email protected]",
)

print(registered.identity.wimse_uri)
print(registered.api_key)  # save this now

TypeScript:

const registered = await client.agents.register({
  name: "Billing Orchestrator",
  external_id: "billing-orchestrator",
  sub_type: "orchestrator",
  trust_level: "first_party",
  created_by: "[email protected]",
});

console.log(registered.identity.wimse_uri);
console.log(registered.api_key); // save this now

This call creates:

• A persistent identity record in the agent registry

• A WIMSE/SPIFFE URI for the agent

• An API key with the zid_sk_ prefix

Step 5: Exchange the API Key for a Short-Lived Token

Python:

token = client.tokens.issue(
    grant_type="api_key",
    api_key=registered.api_key,
)

print(token.token_type)
print(token.expires_in)
print(token.access_token[:48] + "...")

TypeScript:

const token = await client.tokens.issue({
  grant_type: "api_key",
  api_key: registered.api_key,
});

console.log(token.token_type);
console.log(token.expires_in);
console.log(token.access_token.slice(0, 48) + "...");

At this point, your agent has a short-lived JWT it can present to downstream APIs.

Step 6: Inspect Discovery and Introspection Endpoints

JWKS:

curl http://localhost:8899/.well-known/jwks.json

OAuth server metadata:

curl http://localhost:8899/.well-known/oauth-authorization-server

Token introspection:

info = client.tokens.introspect(token.access_token)
print(info.active)

What You Should Understand Before Moving On

• The admin API uses X-Account-ID and X-Project-ID tenant headers.

• The public OAuth endpoints do not use tenant headers directly; tenant context is derived from credential material.

• The API key is not your runtime credential. It is a bootstrap secret used to obtain a short-lived JWT.

What's Next?

• Read Identity Model to understand how ZeroID models agents, services, and applications.

• Read Token Flows to choose the right grant type.

• Continue to Agent Delegation if you need orchestrator to sub-agent delegation.