# auth.md

Nodedistro supports agentic registration for **machine-to-machine** integration APIs. This service uses out-of-band API key provisioning (not dynamic `POST /agent/auth` credential issuance).

- **Resource server (API):** `https://nodedistro.com/api/integration/verify`
- **Authorization server (discovery host):** `https://nodedistro.com`

## 1. Discover

### 1a. Bootstrap from a 401

Request the protected resource without credentials:

```http
GET https://nodedistro.com/api/integration/verify
```

On `401 Unauthorized`, read `WWW-Authenticate`:

```http
WWW-Authenticate: Bearer realm="nodedistro", resource_metadata="https://nodedistro.com/.well-known/oauth-protected-resource"
```

### 1b. Protected Resource Metadata

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

Read: `resource`, `resource_name`, `authorization_servers`, `scopes_supported`, `bearer_methods_supported` (must include `header`).

### 1c. Authorization Server metadata

Fetch `/.well-known/oauth-authorization-server` on the issuer from PRM:

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

Read the `agent_auth` block in full:

| Field | Value |
|-------|-------|
| `skill` | `https://nodedistro.com/auth.md` |
| `register_uri` | `https://nodedistro.com/api/agent/auth` |
| `claim_uri` | `https://nodedistro.com/contact` |
| `identity_types_supported` | `["anonymous"]` |
| `anonymous.credential_types_supported` | `["api_key"]` |

If anything in this file conflicts with PRM or AS metadata, **PRM and AS JSON are authoritative**.

## 2. Pick a method

| What you have | Method |
|---------------|--------|
| Pre-provisioned integration token (env var on hub + property) | **anonymous / out-of-band** |
| ID-JAG from an agent provider | **Not supported** |
| User email only (OTP claim) | **Not supported** — use `https://nodedistro.com/contact` for human onboarding |

Cross-check your choice against `identity_types_supported` in `agent_auth` before proceeding.

## 3. Register

Nodedistro does **not** issue credentials via `POST /agent/auth`. Tokens are provisioned out-of-band:

| Property | Hub environment variable |
|----------|--------------------------|
| Minecraft hosting | `MINECRAFT_HOSTING_SERVICE_TOKEN` |
| Velo Repair | `VELO_REPAIR_SERVICE_API_TOKEN` |

`POST https://nodedistro.com/api/agent/auth` returns `501` with a JSON pointer back to this file:

```json
{
  "error": "not_implemented",
  "message": "Integration tokens are provisioned out-of-band.",
  "auth_md": "https://nodedistro.com/auth.md"
}
```

For new integrations, contact the team via `https://nodedistro.com/contact`.

## 4. Use the credential

Present the API key as a Bearer token:

```http
GET https://nodedistro.com/api/integration/verify
Authorization: Bearer <integration_token>
```

Success response:

```json
{
  "ok": true,
  "service": "nodedistro",
  "integration": "nodedistro.com",
  "property": "<matched-property-id>"
}
```

On `401`, repeat discovery from step 1 — the token may be revoked or misconfigured.

## 5. Errors

| Code / status | Meaning | Action |
|---------------|---------|--------|
| `401` | Missing or invalid token | Verify env var matches hub; re-run discovery |
| `503` | Token not configured on hub | Set hub integration env vars |
| `501` on register | Dynamic registration disabled | Use out-of-band provisioning (section 3) |

## 6. Revocation

Agents do not call a revocation endpoint. Rotate or remove tokens in deployment configuration on the hub and each property.

## Other discovery

- API catalog: https://nodedistro.com/.well-known/api-catalog
- Agent skills: https://nodedistro.com/.well-known/agent-skills/index.json
- MCP server card: https://nodedistro.com/.well-known/mcp/server-card.json