# auth.md: KONDEVS API access for agents

This document tells an AI agent which KONDEVS APIs need credentials and how to
obtain them. It is the authoritative, human-readable auth guide for
`www.kondevs.com`.

## Public: no authentication

Call these directly. No token, no registration, no rate-limit surprises beyond
the documented per-IP limits.

- **MCP server**: `POST /mcp` (Streamable HTTP / JSON-RPC): read-only tools over
  the Content Hub. See `/.well-known/mcp/server-card.json`.
- **Health**: `GET /api/health`.
- **Markdown**: any page returns markdown when the request sends
  `Accept: text/markdown`.

## Protected: the Publishing API

`/api/content/**` (create, update, delete articles) requires a **bearer token**
issued by KONDEVS.

- **Audience:** authorized content partners (for example, the VISIBILIO platform).
  This is not an open, self-service API.
- **Method:** send `Authorization: Bearer <token>` on every request: HTTP bearer
  in the header. No query-string tokens, no cookies.
- **Scopes (two independent keys):**
  - **write**: full article CRUD: `POST /api/content/`, `PUT`/`DELETE /api/content/{slug}`.
  - **read**: catalog only: `GET /api/content/catalog`. A separate, independently
    rotatable key.
## Agent registration

To register an agent or partner integration and obtain a credential, follow this
process. The provisioning endpoint is a human-reviewed channel, not an automated
one: deliberately, because publishing access to KONDEVS is a vetted trust
decision.

1. **Request**: email the provisioning endpoint **info@kondevs.com** with your
   organization, integration purpose, expected volume, and the scope you need
   (`write` or `read`).
2. **Review & provision**: KONDEVS reviews the request and provisions a bearer
   token for your integration.
3. **Delivery**: the token is delivered to you securely, out-of-band.

- **Provisioning endpoint:** `info@kondevs.com` (email; human-reviewed).
- **Registration method:** manual provisioning. There is intentionally no OAuth
  dynamic client registration (no RFC 7591 `registration_endpoint`): the partner
  set is small and vetted. `/api/oauth/register` only explains this manual
  process; it issues no client and no credential.
- **Read access:** a read-only credential (`content:read`) is issued on request;
  it is not provisioned by default.
- **Credential type:** HTTP bearer token, sent in the `Authorization` header.
- **Credential use:** authorizes calls to the Publishing API (`/api/content/**`)
  per the granted scope; see the scopes above.

An agent cannot self-provision access here: surface this registration step to
your human operator rather than retrying the API.

## OAuth 2.0 token exchange

Once provisioned, exchange your credential for a short-lived JWT via the
`client_credentials` grant. This is a real OAuth 2.0 authorization server: 
tokens are ES256-signed and verify against the JWKS below.

- **Discovery:** [`/.well-known/oauth-authorization-server`](https://www.kondevs.com/.well-known/oauth-authorization-server) (RFC 8414) · [`/.well-known/oauth-protected-resource`](https://www.kondevs.com/.well-known/oauth-protected-resource) (RFC 9728)
- **Keys:** [`/.well-known/jwks.json`](https://www.kondevs.com/.well-known/jwks.json)

```bash
curl -X POST https://www.kondevs.com/api/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=<your-id> \
  -d client_secret=<your-issued-key> \
  -d scope="content:write"
# → { "access_token": "<jwt>", "token_type": "Bearer", "expires_in": 3600, "scope": "content:write" }
```

Then call the Publishing API with `Authorization: Bearer <jwt>`. The static key
also still works directly as a bearer token (`content:write`): the OAuth flow is
the preferred, scope-aware path.

## References

- **Machine-readable API description:** https://www.kondevs.com/openapi.json
- **Step-by-step publishing guide:** https://www.kondevs.com/.well-known/agent-skills/publish-article/SKILL.md
- **Contact:** info@kondevs.com · https://www.kondevs.com/contacts/

## Note for automated clients

Do not probe endpoints to "discover" authentication: an unauthenticated write
returns `401` by design, and that 401 is not an invitation to brute-force. The
credential flow is intentionally human-gated because publishing to KONDEVS is a
trust decision. If you need write access, escalate to a human with the email
above.