# auth.md — agent registration for Synthropia

This file tells AI agents how to register for and authenticate with Synthropia's
agent-facing APIs. Audience: autonomous agents acting for a business that wants
an AI phone receptionist, and their developers.

## Current state

The public website API (`POST /api/contact`, `GET /api/status`, documented at
https://synthropia.ai/docs/api with an OpenAPI contract at
https://synthropia.ai/openapi.json) needs no credentials today.

OAuth 2.0 / OpenID Connect for agent API access is planned but not yet live.
Until the token endpoint is operational, agent credentials are provisioned
manually after a request through the contact form. Nothing here requires
payment to register.

## How an agent registers today

1. Read the API documentation: https://synthropia.ai/docs/api
2. Register interest via the registration endpoint: https://synthropia.ai/contact
   (the `register_uri` in our authorization-server metadata). Include the
   operator's name, business, contact email, and the scopes needed below.
3. We reply by email with credentials and the exact `authorization_servers`
   entry to use.

Supported method: `anonymous` pre-registration (no credential needed to ask),
then API keys issued out of band. Supported scopes: `contact:write`,
`status:read`. Credentials are sent in the HTTP `Authorization` header
(`bearer_methods_supported: ["header"]`).

## Machine-readable discovery

- Protected resource metadata (RFC 9728):
  https://synthropia.ai/.well-known/oauth-protected-resource
  (`resource`, `authorization_servers`, `scopes_supported`,
  `bearer_methods_supported`).
- Authorization server metadata (RFC 8414), including the `agent_auth` block
  with `skill`, `register_uri`, and supported identity types:
  https://synthropia.ai/.well-known/oauth-authorization-server
- OpenID Connect discovery:
  https://synthropia.ai/.well-known/openid-configuration
- JSON Web Key Set: https://synthropia.ai/.well-known/jwks.json

Contact: contact@synthropia.ai