# Jetty auth.md

You are an agent. This document tells you how to obtain a credential for Jetty and how to use it. Follow the steps in order.

Jetty (https://jetty.io) runs runbooks: markdown files that give an agent a job, a bar for "done", and checks. Its API is served from `https://flows-api.jetty.io`. This file is the readable companion to the machine discovery documents listed at the end.

## Who this is for

- Coding agents (Claude Code, Codex, Cursor, OpenCode, Antigravity) acting for a person who wants to deploy and run runbooks.
- Any HTTP client that calls the Jetty REST API or its OpenAI-compatible endpoint.

Browser sessions on jetty.io are a separate, cookie-based login. Agents do not use them.

## Credential types

| Credential | Issued by | Shape | Scope | Lifetime |
|---|---|---|---|---|
| API key | https://jetty.io | opaque bearer token, prefix `mlc_` | one workspace (a *collection*) | until revoked |
| User access token | https://clerk.jetty.io (OAuth 2.0) | JWT, `iss` = `https://clerk.jetty.io` | the user's workspaces | short-lived, refreshable |

API keys are what agents should hold. User access tokens exist for OAuth clients Jetty has registered (today: the Jetty CLI's `jetty login`); Clerk does not offer dynamic client registration, so an unknown client cannot obtain one. Both credentials are presented the same way (Step 4).

## Step 1 — Check for an existing credential

Look, in order, at the `JETTY_API_TOKEN` environment variable and the file `~/.config/jetty/token`. If either holds a value, validate it:

```http
GET https://flows-api.jetty.io/api/v1/auth/whoami
Authorization: Bearer mlc_…
```

`200` returns the identity and collection the token resolves to: you are done, go to Step 4. `401` means the token is invalid or revoked: continue to Step 2. Never print the token; refer to it as `mlc_…xxxx`.

## Step 2 — Register

Registration is agent-driven with one human input, the user's email. It is bound to a completed run of Jetty's hosted demo runbook: the run needs no account, costs the user nothing, and the workspace it creates becomes theirs. In auth.md terms this is an `anonymous` registration with an email hint: no identity is asserted, the credential is issued at once, and the human claims the workspace later through an emailed link (Step 3).

Do not perform these calls during passive scans or health checks. Registration creates a workspace and sends email.

### 2a. Start the demo run

```http
POST https://jetty.io/api/demo/run
Content-Type: application/json

{ "collection_name": "optional-workspace-name" }
```

`collection_name` is optional (3–48 characters: letters, digits, hyphens, underscores; no leading, trailing, or repeated separators). The response carries a signed `run_id`, the `collection` (workspace) name, and `estimated_seconds`. Rate limit: 3 demo runs per IP per hour (`429`).

### 2b. Wait for it to finish

```http
GET https://jetty.io/api/demo/status/{run_id}
```

Poll every 10–15 seconds until `status` is `completed`. `failed` or `cancelled` are terminal too: fall back to the human-attended path below. `steps_completed` lists progress you may relay to the user.

### 2c. Ask the human for their email

This is the only human step. Say what will happen: Jetty will create a workspace for that address, send one email with a link to claim it, and hand you an API key for it now. Proceed only with their consent.

### 2d. Mint the credential

```http
POST https://jetty.io/api/onboarding/email-signup
Content-Type: application/json

{ "email": "user@example.com", "demo_run_id": "{run_id}", "source": "your-agent-name" }
```

Response (`200`):

```json
{
  "collection": "…",
  "api_key": "mlc_…",
  "dashboard_url": "https://jetty.io/sign-up?claim=…",
  "trial_runs": 12,
  "success": true
}
```

`source` is an optional slug (`[a-z0-9_-]{1,64}`) naming your agent. Errors: `400` invalid email or missing/invalid `demo_run_id`, `404` run not found, `409` the workspace was already claimed, `429` rate limit (5 registrations per IP per hour, 3 per email per day).

### 2e. Store it

Write `api_key` to `~/.config/jetty/token` with mode `0600` (directory `~/.config/jetty` mode `0700`). Never write it into project files or logs.

If the Jetty plugin is installed, its `jetty-setup` skill performs 2a–2e for you (`jetty_simulate.py run`, then `jetty_simulate.py claim --email …`).

### Alternative registration paths

- **Human-attended sign-up.** The user creates an account at https://jetty.io/sign-up, then creates a key at https://jetty.io/settings/api-keys and pastes it to you. Read it interactively (`read -rs`); never ask for it in a shared channel.
- **OAuth 2.0 (registered clients only).** The Jetty CLI's `jetty login` runs the authorization-code flow with PKCE against `https://clerk.jetty.io/oauth/authorize` with a loopback redirect and exchanges the code at `https://clerk.jetty.io/oauth/token`. Scopes: `email profile offline_access user:org:read`. Only client IDs Jetty has registered are accepted.

## Step 3 — Claim (human, optional)

The email from Step 2d contains a claim link (also returned as `dashboard_url`). When the user signs up or signs in through it, the workspace attaches to their account: they get the web dashboard, billing, and the ability to add or revoke keys. The API key keeps working before and after the claim, so there is nothing for you to poll.

## Step 4 — Use the credential

Send it as a bearer token on every request to `https://flows-api.jetty.io`:

```http
POST https://flows-api.jetty.io/api/v1/run/{collection}/{task}
Authorization: Bearer mlc_…
Content-Type: application/json
```

- API keys are scoped to one collection. A request against another collection returns `403`.
- `401` (with `WWW-Authenticate: Bearer`) means the token is missing, invalid, or revoked. Go back to Step 1.
- New workspaces start with 12 free runs; after that, claim the workspace and choose a plan at https://jetty.io/pricing.
- The OpenAPI description is at https://flows-api.jetty.io/openapi.json; the reference is at https://jetty.io/docs/reference/api.

## Step 5 — Rotate or revoke

With a valid key for the collection:

- List keys: `GET https://flows-api.jetty.io/api/v1/api-keys/collection/{collection}`
- Create another: `POST https://flows-api.jetty.io/api/v1/api-keys/` with `{ "name": "…", "collection_name": "{collection}" }`
- Revoke: `DELETE https://flows-api.jetty.io/api/v1/api-keys/{api_key_id}`

Humans can do the same at https://jetty.io/settings/api-keys. OAuth access tokens are revoked at `https://clerk.jetty.io/oauth/token/revoke` (RFC 7009).

## Machine-readable discovery

- Protected resource metadata (RFC 9728): https://jetty.io/.well-known/oauth-protected-resource
- Authorization server metadata (RFC 8414, with the `agent_auth` block): https://jetty.io/.well-known/oauth-authorization-server
- Clerk's OAuth and OIDC discovery: https://clerk.jetty.io/.well-known/oauth-authorization-server and https://clerk.jetty.io/.well-known/openid-configuration
- API catalog (RFC 9727): https://jetty.io/.well-known/api-catalog
- MCP Server Card: https://jetty.io/.well-known/mcp/server-card.json (the server runs locally: `npx -y jetty-mcp-server` with `JETTY_API_TOKEN` set)
- Agent skills index: https://jetty.io/.well-known/agent-skills/index.json
- ARD capability manifest: https://jetty.io/.well-known/ai-catalog.json
- Docs index for agents: https://jetty.io/llms.txt
- Onboarding trigger and deep reference: https://jetty.io/agent-instructions.md, https://jetty.io/MACHINE_CONTEXT.md

Any HTML page on jetty.io returns Markdown when requested with `Accept: text/markdown`.
