# auth.md — Kroonen AI Agent Registration

Kroonen AI publishes the discovery and authentication metadata below so autonomous
agents can find, authenticate to, and use this site's APIs. This document is the
human- and agent-readable entry point for registration.

## Audience

Agents and their operators that want to programmatically read Kroonen AI data or act
on the site's behalf (for example, to submit contact messages with proper provenance).

## Discovery

| Document | URL |
| --- | --- |
| API catalog (RFC 9727) | https://www.kroonen.ai/.well-known/api-catalog |
| OpenAPI spec | https://www.kroonen.ai/docs/openapi.json |
| API documentation | https://www.kroonen.ai/docs/api/ |
| OAuth Authorization Server metadata (RFC 8414) | https://www.kroonen.ai/.well-known/oauth-authorization-server |
| OpenID Connect metadata | https://www.kroonen.ai/.well-known/openid-configuration |
| Protected Resource metadata (RFC 9728) | https://www.kroonen.ai/.well-known/oauth-protected-resource |
| JWKS | https://www.kroonen.ai/.well-known/jwks.json |
| MCP server card (SEP-1649) | https://www.kroonen.ai/.well-known/mcp/server-card.json |
| Agent skills index | https://www.kroonen.ai/.well-known/agent-skills/index.json |
| ARD manifest | https://www.kroonen.ai/.well-known/ai-catalog.json |

## Current public surface

The endpoints published in the API catalog are **public and unauthenticated** today:

- `GET /api/genesis-status` — read-only training telemetry.
- `POST /api/contact` — Turnstile-gated; intended for humans, not automated agents.

No `Authorization` header is required for the public surface at present.

## Authentication (OAuth 2.0)

For authenticated programmatic access, the site advertises an OAuth 2.0 authorization
server via the metadata above. The intended flows:

- **Authorization code + PKCE (`S256`)** — for agents acting on a user's behalf.
- **Client credentials** — for server-to-server integration.

Supported scopes:

- `public:read` — read public site and product data.
- `contact:write` — submit contact messages on the owner's behalf.

Client registration is advertised at `register_uri`. The signing key is published in the
JWKS (`kid: kroonen-ai-2026`). Identity assertions are supported (ID-JAG /
`urn:ietf:params:oauth:token-type:id-jag` and `verified_email`), and an anonymous
credential type is available where registration is not required.

## Registration & credential use

1. Fetch the Authorization Server metadata at
   `/.well-known/oauth-authorization-server`.
2. Register (or provision) a client; where no registration is required, proceed
   anonymously using the advertised anonymous credential type.
3. Obtain an access token for the required scope(s) and present it as a
   `Bearer` token in the `Authorization` header.

> **Note:** The OAuth endpoints above describe the intended, future authentication
> posture. The public surface is currently open; treat the metadata as the source of
> truth for what will be enforced and check it before relying on any token.

## Contact

Questions about agent access: [hello@kroonen.ai](mailto:hello@kroonen.ai)