# AUTH.md

_Agent authentication manifest for DomiSol (`domisol.app`)._

This document tells automated clients and AI agents how to authenticate with
DomiSol's public surfaces. It is intentionally short because DomiSol's public
API is **read-only and open by default** — most agents need no credentials at
all, and there is no registration step.

## Discover

- **API base:** `https://us-central1-domisol-prod.cloudfunctions.net/publicApi`
- **Catalog (RFC 9727):** <https://domisol.app/.well-known/api-catalog>
- **Description (OpenAPI 3.1):** <https://domisol.app/.well-known/openapi.json>
- **Guide:** <https://domisol.app/docs/api.md>

## Authenticate

There is **no agent registration** and **no OAuth flow**. Two modes:

1. **Anonymous (default).** The API only returns data authors have already
   published via a share link, so it requires no credentials and is open to any
   origin (CORS `*`). Just send a plain `GET`.

2. **Optional API key.** The operator may enable an allowlist. When enabled,
   requests to `GET /v1/scores/{slug}` must carry a matching key in an
   `x-api-key` header (the `/v1/stats` and `/v1/health` endpoints stay open).
   Request a key by emailing **hello@domisol.app** — it is a static shared
   secret, not a token issued by an authorization server.

```
# anonymous
curl https://us-central1-domisol-prod.cloudfunctions.net/publicApi/v1/scores/{slug}

# with an issued key
curl -H "x-api-key: YOUR_KEY" \
  https://us-central1-domisol-prod.cloudfunctions.net/publicApi/v1/scores/{slug}
```

## Use

See the guide at <https://domisol.app/docs/api.md> and the
[OpenAPI description](https://domisol.app/.well-known/openapi.json) for the
available endpoints and response shapes. To interpret returned scores, load the
`domisol-notation` skill from
<https://domisol.app/.well-known/agent-skills/index.json>.

## No OAuth / OIDC authorization server

DomiSol does **not** operate an OAuth/OIDC authorization server and has no
token-gated API. It therefore does **not** publish
`/.well-known/oauth-authorization-server`, `/.well-known/openid-configuration`,
or `/.well-known/oauth-protected-resource` — publishing those would advertise
issuer, token, and registration endpoints that cannot issue or accept tokens,
which would only mislead an agent. App sign-in for human users runs on Firebase
Authentication (Google's identity platform) and does not mint tokens for this
API. If a token-gated write API is ever added, this manifest and the matching
OAuth metadata will be published together — see `docs/agent-readiness.md`.

## Contact

Questions, partnership, or an API key: **hello@domisol.app**.