# auth.md

Agent authentication and registration guide for **Avernic RSPS** public APIs.

## Audience

This document is for automated agents that want to discover and call **public, non-sensitive** Avernic APIs (status, highscores, updates, store catalog, launcher metadata, promotions).

Privileged surfaces are **out of scope** for third-party agents:

- Admin panel APIs
- Payment webhooks
- Game-server claim / auth sync
- Heartbeat push endpoints requiring server keys

Do not request or expect those secrets.

## Public access model

Most published endpoints are **anonymous read** APIs. No OAuth access token is required to call:

- `GET https://avernic.net/status.json`
- `GET https://avernic.net/api/highscores`
- `GET https://avernic.net/api/updates`
- `GET https://avernic.net/api/products`
- `GET https://avernic.net/api/launcher/config`
- `GET https://avernic.net/promotions/active`

Discovery documents:

- API catalog: `https://avernic.net/.well-known/api-catalog`
- OpenAPI: `https://avernic.net/openapi.json`
- Human docs: `https://avernic.net/developers`
- Protected Resource Metadata: `https://avernic.net/.well-known/oauth-protected-resource`
- Authorization Server Metadata: `https://avernic.net/.well-known/oauth-authorization-server`

## Step 1 — Discover

1. Fetch `https://avernic.net/.well-known/api-catalog` (`Accept: application/linkset+json`).
2. Follow `service-desc` links to OpenAPI documents.
3. Optionally fetch this file (`https://avernic.net/auth.md`) for registration policy.

## Step 2 — Choose a registration method

Supported for agents:

- **anonymous** — recommended for public read APIs. No user account is created.

Not supported for third-party agents:

- identity assertion / ID-JAG
- verified email claim ceremonies
- game-server key provisioning

## Step 3 — Register (anonymous)

`POST https://avernic.net/agent/auth`

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

Response (example):

```json
{
  "ok": true,
  "token_type": "Bearer",
  "access_token": "public",
  "scope": "api.public.read",
  "expires_in": 86400,
  "note": "Public APIs do not require a credential. The access_token value public is informational."
}
```

## Step 4 — Call public APIs

You may omit `Authorization` entirely for public GET endpoints.

If you send a header, use:

```http
Authorization: Bearer public
```

## Credential use

- Scope `api.public.read` covers published read-only endpoints listed in OpenAPI.
- Tokens do not grant admin, checkout mutation beyond normal public store UX, webhook, or game-server privileges.
- There is no privileged agent credential issuance on this host.

## Revocation

Anonymous public tokens are informational and expire automatically. No privileged agent credentials are issued, so revocation is a no-op for public access.