# auth.md

Agent authentication and registration for **Plateau Candy** — https://www.plateaucandy.de

This document tells autonomous agents and AI clients how to call Plateau Candy's
APIs and how to obtain credentials for protected resources.

## Audience

Autonomous agents, AI assistants and MCP clients acting on behalf of a user or
organisation that want to read Plateau Candy's capabilities, cases and metadata,
or call its tools.

## Public access (no authentication)

Most discovery and read endpoints are public and need no credentials:

- Agent card: `/.well-known/agent-card.json`
- Agent documentation: `/agent`
- Markdown representations: `/index.md`, `/content.md`
- OpenAPI spec: `/api/openapi.json`
- API catalog: `/.well-known/api-catalog`
- Search: `/api/search`
- MCP server: `/.well-known/mcp` (also `/.well-known/mcp.json`)

## Authenticated access (OAuth 2.0)

Protected resources use OAuth 2.0. Discover authorization servers and resource
metadata via the standard well-known endpoints below.

```yaml
agent_auth:
  skill: oauth2
  register_uri: https://www.plateaucandy.de/.well-known/oauth-authorization-server
  methods:
    - type: oauth2
      authorization_server: https://www.plateaucandy.de/.well-known/oauth-authorization-server
      protected_resource_metadata: https://www.plateaucandy.de/.well-known/oauth-protected-resource
      bearer_methods_supported: [header]
```

- OAuth Authorization Server metadata (RFC 8414): `/.well-known/oauth-authorization-server`
- OAuth Protected Resource metadata (RFC 9728): `/.well-known/oauth-protected-resource`

Present the access token in the `Authorization: Bearer <token>` request header.

## Pick a method

For public read and write endpoints, no method selection is needed — call them
directly (identity type `anonymous`). For partner endpoints, OAuth 2.0 bearer
tokens are the only supported method; there is no API-key or basic-auth path.

## Claim

Partner credentials are issued out-of-band after a short qualification
(`register_uri` above). There is no self-serve claim endpoint; the issued
bearer token is delivered directly and is active immediately.

## Errors

Authentication failures return `application/problem+json` (RFC 9457): `type`,
`title`, `status`, `detail`, plus a stable machine-readable `code` extension.
A legacy `error` object (`code`, `message`, `status`) is included for older
clients. A `401` means the bearer token is missing or invalid; a `403` means
the token lacks the required scope. Retry with corrected credentials — there
is no lockout.

## Revocation

To revoke a partner token, email [hi@plateaucandy.de](mailto:hi@plateaucandy.de)
from the registered contact address. Revocation is processed manually within
one business day; there is no self-serve revocation endpoint.

## Contact

Agent or operator questions: noema@plateaucandy.de