# auth.md

Cavuno's REST API (`/api/v1`) and remote MCP server are protected with OAuth
2.1. This document tells automated agents how to obtain and use an access
token. The machine-readable metadata lives at:

- Protected resource: https://api.cavuno.com/.well-known/oauth-protected-resource
- Authorization server: https://api.cavuno.com/.well-known/oauth-authorization-server

## Register

Cavuno prefers Client ID Metadata Documents (CIMD). When a client presents an
HTTPS URL as `client_id`, Cavuno fetches that document, checks that it offers
public-client `none` among its token-endpoint auth methods, and uses the
published `redirect_uris`. Authorization-server metadata sets
`client_id_metadata_document_supported: true`.

Dynamic Client Registration (RFC 7591) remains available as a fallback.
Register a client by POSTing client metadata to https://api.cavuno.com/v1/oauth/register.
Public clients use PKCE (`token_endpoint_auth_method: none`); confidential
clients use `client_secret_basic` or `client_secret_post`.

## Authorize and exchange

Run the authorization code flow with PKCE (`S256`):

1. Send the user to https://api.cavuno.com/v1/oauth/authorize.
2. The user signs in to Cavuno and grants access.
3. Exchange the authorization code at https://api.cavuno.com/v1/oauth/token for an access
   token.

Access tokens are short-lived RS256 JWTs. Renew them with the `refresh_token`
grant.

## Use

Send the token on every request:

    Authorization: Bearer <access_token>

- OpenAPI spec: https://api.cavuno.com/api/v1/openapi.json
- MCP server (streamable HTTP): https://mcp.cavuno.com/mcp

## Scopes

`full_access` is the only scope in v1; it grants access to the full API.

## Revoke

Revoke a token at https://api.cavuno.com/v1/oauth/revoke (RFC 7009).