# 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:

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

Expected response:

```json
{
  "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:

```bash
pip install highflame cryptography PyJWT
```

TypeScript:

```bash
npm install @highflame/sdk
```

#### Step 3: Create a Client

Python:

```python
from highflame.zeroid import ZeroIDClient

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

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

TypeScript:

```typescript
import { ZeroIDClient } from "@highflame/sdk";

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:

```python
registered = client.agents.register(
    name="Billing Orchestrator",
    external_id="billing-orchestrator",
    sub_type="orchestrator",
    trust_level="first_party",
    created_by="dev@company.com",
)

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

TypeScript:

```typescript
const registered = await client.agents.register({
  name: "Billing Orchestrator",
  external_id: "billing-orchestrator",
  sub_type: "orchestrator",
  trust_level: "first_party",
  created_by: "dev@company.com",
});

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:

```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:

```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:

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

OAuth server metadata:

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

Token introspection:

```python
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**](/agent-identity-zeroid/concepts/identity-model.md) to understand how ZeroID models agents, services, and applications.
* Read [**Token Flows**](/agent-identity-zeroid/concepts/token-flows.md) to choose the right grant type.
* Continue to [**Agent Delegation**](/agent-identity-zeroid/guides/agent-delegation.md) if you need orchestrator to sub-agent delegation.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.highflame.ai/agent-identity-zeroid/quick-start.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.