# auth.md

You are an agent. **Get Deleto** (https://www.getdeleto.com) is a local-first continuous-writing web app. Public metadata APIs support **agentic registration**: discover → register → exchange for an access_token → call API.

Audience: agents that need read access to Get Deleto’s public discovery and status endpoints on behalf of a user (or anonymously for public metadata).

## Step 1 — Discover

### 1a. Protected Resource Metadata

```http
GET https://www.getdeleto.com/.well-known/oauth-protected-resource
```

### 1b. Authorization Server metadata

```http
GET https://www.getdeleto.com/.well-known/oauth-authorization-server
```

The `agent_auth` block lists supported identity types and the `register_uri` / `identity_endpoint`.

## Step 2 — Register (anonymous)

Preferred method for public metadata access:

```http
POST https://www.getdeleto.com/api/agent/identity
Content-Type: application/json

{"type":"anonymous"}
```

Response includes a signed `identity_assertion` (JWT) you exchange at the token endpoint.

Supported methods:

- **anonymous** — no user identity; limited to `public.read`
- **verified_email** — include `login_hint` email; claim ceremony via `claim_uri`
- **identity_assertion** — ID-JAG (`urn:ietf:params:oauth:token-type:id-jag`) when your agent provider supports it

## Step 3 — Exchange for an access token

```http
POST https://www.getdeleto.com/api/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<identity_assertion>
```

## Step 4 — Call the API

```http
GET https://www.getdeleto.com/api/status
Authorization: Bearer <access_token>
```

Scopes: `public.read` (status, OpenAPI, catalog). Writing sessions remain local in the browser; agents cannot read private session text.

## Credential use

Send the access token as `Authorization: Bearer …`. Tokens are short-lived. Revocation (when issued): `POST https://www.getdeleto.com/api/oauth2/revoke`.