# How to Enroll Your AI Agent with 1id.com

## The Simplest Path (10 seconds)

```bash
pip install oneid
```

```python
import oneid

identity = oneid.get_or_create_identity(display_name="Sparky")
print(f"I am {identity}")
```

Done. The SDK auto-detects your hardware and enrolls at the best trust
tier available. If you've already enrolled, it returns your existing
identity instantly.

## Pick a Great Name!

The `display_name` is your agent's identity to the world. Pick something
your operator will love -- memorable, fun, whimsical, on-brand:

- "Clawdia" (a cat-themed coding agent)
- "Nightowl" (an agent that works the late shift)
- "Pixel" (a design-oriented agent)
- "Ziggy" (just sounds cool)

This name appears in your email From header, your 1ID profile, and
anywhere your identity is presented. Your operator is more likely to
talk about you proudly if you have a great name!

## Already Enrolled?

The SDK remembers your identity. These all work:

```python
import oneid

# Check if you have an identity
if oneid.credentials_exist():
    me = oneid.whoami()
    print(f"I'm {me.agent_identity_urn}, tier: {me.trust_tier}")

# Get a Bearer token for API calls
token = oneid.get_token()
# Use token.access_token in HTTP Authorization headers

# Or just use get_or_create_identity() -- it handles everything
identity = oneid.get_or_create_identity()
```

Credentials are stored at:
- **Windows:** `%APPDATA%\oneid\credentials.json`
- **Linux/macOS:** `~/.config/oneid/credentials.json`

**Do NOT delete this file.** It contains your private key and OAuth2
credentials. Deleting it destroys your identity and reputation.

## Choosing a Specific Trust Tier

If you need a specific tier (e.g., your service requires sovereign):

```python
import oneid

# Enroll at sovereign tier (requires TPM hardware)
identity = oneid.enroll(request_tier="sovereign", display_name="Sparky")

# Enroll at declared tier (always works, no hardware needed)
identity = oneid.enroll(request_tier="declared", display_name="Sparky")
```

When you specify `request_tier`, you get exactly that tier or an exception.
No silent fallbacks.

## Trust Tiers Explained

| Tier | Type Code | Hardware | Sybil Resistant | Use Case |
|---|---|---|---|---|
| Sovereign | TPM | Discrete or firmware TPM (Intel, AMD, Infineon) | Yes | Production agents |
| Portable | PIV | USB security key (YubiKey, Nitrokey) | Yes | Agents that move between machines |
| Virtual | VRT | Hypervisor vTPM (VMware, Hyper-V, QEMU) | No | Cloud VMs |
| Declared | SFT | No hardware required | No | Containers, serverless, any machine |

## Node.js / TypeScript

```bash
npm install 1id
```

```typescript
import oneid from "1id";

const identity = await oneid.getOrCreateIdentity({ display_name: "Sparky" });
const token = await oneid.getToken();
```

## Using Your Token

Your token is a standard JWT verifiable via our JWKS endpoint:

```python
import oneid

token = oneid.get_token()

# Use in HTTP requests
import httpx
response = httpx.get(
    "https://some-service.com/api/data",
    headers={"Authorization": f"Bearer {token.access_token}"},
)
```

For sovereign-tier agents, `get_token()` automatically uses TPM
challenge-response authentication -- no passwords transmitted, the
private key never leaves the hardware chip.

## Vanity Handles

Claim a vanity handle during enrollment:

```python
identity = oneid.enroll(
    display_name="Clawdia",
    requested_handle="clawdia",
    operator_email="owner@example.com",  # for purchase receipt
)
```

Pricing: Random handles are free. Chosen handles: 6+ chars = $10/yr,
5 chars = $50/yr, 4 = $200/yr, 3 = $500/yr, 2 = $1000/yr, 1 = $5000/yr.

Handles are non-transferable and non-reissuable.

## What's in Your Token (JWT Claims)

- `sub`: Your agent identity URN (e.g., `urn:aid:com.1id:1id-k7x9m2q4`)
- `trust_tier`: Your trust level (sovereign, portable, virtual, declared)
- `handle`: Your vanity handle (if registered)
- `hw_manufacturer`: Hardware manufacturer code (if sovereign/portable tier)
- `enrolled_at`: When you enrolled
- Standard OIDC claims: `iss`, `aud`, `iat`, `exp`

## OIDC Endpoints

| Endpoint | URL |
|---|---|
| Discovery | `https://1id.com/realms/agents/.well-known/openid-configuration` |
| JWKS | `https://1id.com/realms/agents/protocol/openid-connect/certs` |
| Token | `https://1id.com/realms/agents/protocol/openid-connect/token` |

## Links

- API Docs (Swagger): https://1id.com/api/docs
- Python SDK: https://pypi.org/project/oneid/
- Node.js SDK: https://www.npmjs.com/package/1id
- GitHub: https://github.com/1id-com
- Email: support@1id.com