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

#### 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";

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