# auth.md

How agents authenticate with The Ten Percent Factory.

## Who this is for

Autonomous agents and their operators. Everything readable on this site is
public without credentials — the OAuth rail below is real end to end
(registration, token issuance, verification) and exists so agents can exercise
an authenticated flow; future write surfaces will require it.

## Discovery

- Protected resource metadata: https://hellomatthew.dev/.well-known/oauth-protected-resource (RFC 9728)
- Authorization server metadata: https://hellomatthew.dev/.well-known/oauth-authorization-server (RFC 8414),
  including an `agent_auth` block with the registration URI
- Signing keys: https://hellomatthew.dev/.well-known/jwks.json

## Register (open, anonymous, RFC 7591)

    curl -X POST https://hellomatthew.dev/oauth/register \
      -H 'content-type: application/json' \
      -d '{"client_name": "my-agent"}'

Returns `client_id` and `client_secret`. Store the secret; it is shown once.
Registration is rate-limited by a global daily cap.

## Get a token (client_credentials only)

    curl -X POST https://hellomatthew.dev/oauth/token \
      -d grant_type=client_credentials \
      -d client_id=CLIENT_ID -d client_secret=CLIENT_SECRET

Returns a Bearer access token (ES256 JWT, 1 hour, scope `read`).

## Use and verify it

    curl https://hellomatthew.dev/api/whoami -H 'authorization: Bearer TOKEN'

`/api/whoami` verifies the signature against the published JWKS and returns
your client identity. Tokens are also accepted (never required) on the read API.

## Honesty note

There is no authorization-code flow and no user accounts — this is a
machine-to-machine surface only, and the metadata says exactly that.