# KruxOS auth.md

> Agent authentication and credential provisioning for KruxOS appliances.

## Audience

This document is for AI agents and agent frameworks connecting to a KruxOS appliance. The kruxos.com website is public and requires no authentication.

## Two principals

KruxOS distinguishes the human operator (`User`) from autonomous code (`Agent`). Each principal has separate credentials and audit attribution.

| Principal | Port | Credential | Format |
|-----------|------|------------|--------|
| **Agent** | 7700 (MCP WebSocket) | API key | 64-char hex |
| **User** (operator/CLI) | 7703 (HTTP, loopback) | Bearer token | `krx_user_<base64url>` |
| **Operator** (dashboard) | 7800 (HTTPS) | Passphrase | bcrypt hash from vault step |

## Agent authentication (MCP :7700)

Agents **must** authenticate with an API key. There is no anonymous MCP access.

```
Endpoint:  ws://<host>:7700/mcp
Transport: WebSocket
Auth:      Authorization: Bearer <64-char-hex>
           or ws://<host>:7700/mcp?token=<64-char-hex>
```

### Provisioning an agent key

1. **First-boot wizard** — AdminAgent (Identity) step creates the first agent and displays its key once
2. **CLI** — `kruxos agent create --name <name> [--purpose "..."]`
3. **Dashboard** — Agents page → Create

```bash
kruxos agent create --name deploy-bot --purpose "CI/CD agent"
# Token shown once — save immediately
```

Revoke: `kruxos agent revoke <name>`. Rotate: `kruxos agent rotate <name>`.

## User API authentication (:7703)

Opaque bearer tokens for operator CLI and automation bridges:

```http
Authorization: Bearer krx_user_...
```

### Provisioning a User token

1. **First-boot wizard** — step 6 (User token), shown once
2. **CLI** — `kruxos user-token create --label <label>`
3. **Dashboard** — Settings → Tokens

Environment variable for bridges: `KRUXOS_USER_TOKEN` (not `KRUXOS_TOKEN`).

Revoke: `kruxos user-token revoke <id>` or Dashboard. Returns `401` immediately.

## Supervision WebSocket (:7701)

Requires `krx_user_*` bearer or an active operator dashboard session.

## Discovery metadata

| Resource | URL |
|----------|-----|
| OAuth Authorization Server | `https://kruxos.com/.well-known/oauth-authorization-server` |
| Protected Resource Metadata | `https://kruxos.com/.well-known/oauth-protected-resource` |
| MCP server card | `https://kruxos.com/.well-known/mcp/server-card.json` |
| API catalog | `https://kruxos.com/.well-known/api-catalog` |

## Further reading

- [Agent setup](https://kruxos.com/agents/setup/)
- [MCP gateway docs](https://docs.kruxos.com/developers/api/gateway-mcp/)
- [REST API / tokens](https://docs.kruxos.com/developers/api/rest-api/)
- [Auth skill](https://kruxos.com/.well-known/agent-skills/kruxos-auth/SKILL.md)