# Kleinanzeigen Agent auth.md

This document explains how AI clients authenticate to the Kleinanzeigen Agent MCP server, A2A endpoint, and REST API. It does not create a Kleinanzeigen user account autonomously. A human owns the account, approves OAuth access where supported, and pays for the credits used by tools and API requests.

## Discovery

- MCP resource: https://api.kleinanzeigen-agent.de/mcp
- Protected Resource Metadata: https://kleinanzeigen-agent.de/.well-known/oauth-protected-resource
- Canonical Protected Resource Metadata: https://api.kleinanzeigen-agent.de/.well-known/oauth-protected-resource/mcp
- Authorization Server Metadata: https://api.kleinanzeigen-agent.de/.well-known/oauth-authorization-server
- MCP Server Card: https://kleinanzeigen-agent.de/.well-known/mcp/server-card.json
- A2A Agent Card: https://kleinanzeigen-agent.de/.well-known/agent-card.json
- MCP documentation: https://kleinanzeigen-agent.de/api/docs-raw/mcp
- A2A documentation: https://kleinanzeigen-agent.de/api/docs-raw/a2a

## agent_auth

```yaml
agent_auth:
  skill: https://kleinanzeigen-agent.de/auth.md
  register_uri: https://api.kleinanzeigen-agent.de/oauth/register
  registration_methods_supported:
    - oauth_dynamic_client_registration_with_user_authorization
```

The registration endpoint registers a public OAuth client, not a new user. It accepts dynamic client registration metadata including at least one HTTPS or local-loopback `redirect_uri`. The client then starts an Authorization Code flow with PKCE. Kleinanzeigen Agent redirects the human user to sign in and shows a consent page before access is granted.

## OAuth method

1. Read the protected-resource and authorization-server metadata.
2. Register a public client at `https://api.kleinanzeigen-agent.de/oauth/register` with `token_endpoint_auth_method=none` and an allowed redirect URI.
3. Open `https://api.kleinanzeigen-agent.de/oauth/authorize` for the user with `response_type=code`, PKCE `S256`, `scope=mcp:kleinanzeigen`, and `resource=https://api.kleinanzeigen-agent.de/mcp`.
4. After the user approves, exchange the authorization code at `https://api.kleinanzeigen-agent.de/oauth/token`.
5. Send the access token as `Authorization: Bearer <token>` to the MCP endpoint.
6. Refresh tokens at the same token endpoint and revoke them at `https://api.kleinanzeigen-agent.de/oauth/revoke` when the connection is removed.

OAuth access tokens last one hour. Refresh tokens last up to 30 days and rotate when used. The only supported OAuth scope is `mcp:kleinanzeigen`.

## API-key method

Older MCP clients, A2A clients, and REST API integrations can use the API key created by the human user in the Kleinanzeigen Agent dashboard:

```http
Authorization: Bearer klaz_live_...
```

REST API and A2A requests can also use `klaz_key: klaz_live_...`. Store credentials in a secret manager or environment variable. Never paste, print, log, commit, or put them in query parameters.

The A2A endpoint is https://api.kleinanzeigen-agent.de/a2a and currently accepts API keys only. MCP OAuth access tokens are resource-bound to https://api.kleinanzeigen-agent.de/mcp and must not be sent to the A2A endpoint.

## Credential failures

On `401`, check which authentication method was used. Refresh an expired MCP OAuth access token first. If refresh fails, repeat user authorization with the existing client registration; register a new client only when the client ID is missing or invalid. Rotate an invalid or exposed API key in the dashboard. Do not probe registration endpoints during passive discovery.