# boxofsynths.com auth.md

The honest version, for agents.

- Browsing presets and packs, /llms.txt, the markdown page versions and
  everything under /.well-known needs no authentication.
- Reading the preset and pack listings, pulling a preset, validating a
  patch and reading the schema all work anonymously.
- Generating a patch and rendering it to audio go further with an
  account or an agent token: an anonymous plugin call is recorded free
  (credits_charged=0); an authenticated call spends credits per the
  costs at /credits (signed in) or the schema endpoint.
- Submitting a preset, voting, buying a pack and downloading a pack need
  a human account (email + password at /register). Agents use the OAuth
  flow below for everything else.

## Agent registration

Real OAuth 2.0, deliberately minimal:

- **Discovery**: /.well-known/oauth-authorization-server and
  /.well-known/oauth-protected-resource are live and truthful.
- **register_uri**: POST /oauth/register (RFC 7591 dynamic client
  registration). Send JSON: `client_name` (required), `contact`
  (optional, an email or URL so we can reach you), `scope` (optional,
  space separated). You get back `client_id` and `client_secret` once;
  store them, they are not shown again.
- **Identity types**: service (a registered client). Anonymous access
  still covers everything read-only.
- **Credential types**: client_secret (client_secret_post or
  client_secret_basic at the token endpoint).
- **Tokens**: POST /oauth/token with `grant_type=client_credentials`.
  Access tokens are RS256 JWTs, one hour, verifiable against
  /.well-known/jwks.json.
- **Scopes**: `presets.read` (currently additive to the already-open
  preset listing; reserved for future gated content), `presets.write`
  (submitting/editing presets over the API), `patches.render` (required
  for POST /api/v1/patches/render), `training.write` (required for POST
  /api/v1/training), `kb.read` (required for GET /api/v1/kb/search).
- **Grants that do not exist**: authorization_code, refresh_token,
  device_code. No user impersonation: tokens identify your agent, never
  a specific person's account.

## Where things live

- Recipe schema + parameter registry: GET /api/v1/schema
- Generate/record a patch: POST /api/v1/generations
- Vote on a generation: POST /api/v1/generations/{uuid}/feedback
- Validate a patch: POST /api/v1/patches/validate
- Render a patch to audio (scope patches.render): POST /api/v1/patches/render
- Submit training data (scope training.write): POST /api/v1/training
- Search the knowledge base (scope kb.read): GET /api/v1/kb/search
