# Auth.md

Agent authentication and registration instructions for ChillAccount.

ChillAccount exposes public read endpoints that require no authentication, plus
authenticated write endpoints secured with JWT bearer tokens.

## Public (no auth required)
- `GET https://chillaccount.com/api/blog` — list published articles
- `GET https://chillaccount.com/api/blog/{slug}` — read an article
- `POST https://chillaccount.com/api/contact/send` — submit a contact enquiry

## Authenticated (JWT bearer)
1. Request a token:

   ```
   POST https://chillaccount.com/api/admin/login
   Content-Type: application/json

   { "username": "<username>", "password": "<password>" }
   ```

   The response contains a `token` (JWT). Accounts must hold the
   "Blog Console (/blog_admin)" permission to create content.

2. Send the token on subsequent requests:

   ```
   Authorization: Bearer <token>
   ```

## Agent registration flow (self-contained)
An autonomous agent can complete registration end-to-end without human help for
read access. The registration endpoint is `https://chillaccount.com/api/agent/register`.

1. Register for read access (anonymous, no credential required):

   ```
   POST https://chillaccount.com/api/agent/register
   Content-Type: application/json

   { "agent_name": "my-agent", "scopes": ["blog:read"] }
   ```

   The response confirms `blog:read` is granted anonymously. No token is needed —
   call the public read endpoints directly.

2. Register for write access (provisioned account):

   ```
   POST https://chillaccount.com/api/agent/register
   Content-Type: application/json

   { "agent_name": "my-agent", "scopes": ["blog:write"], "contact_email": "you@example.com" }
   ```

   The response returns provisioning instructions and the token endpoint
   (`https://chillaccount.com/api/admin/login`). Once provisioned, obtain a JWT via the password grant
   above and send it as `Authorization: Bearer <token>`.

- Identity types supported: `anonymous` (read), password-grant account (write).
- Credential types: `bearer_token` (JWT) for authenticated requests; `none` for anonymous reads.
- Scopes: `blog:read`, `blog:write`.

## Discovery
- Authorization server metadata: `https://chillaccount.com/.well-known/oauth-authorization-server`
- Protected resource metadata: `https://chillaccount.com/.well-known/oauth-protected-resource`
- Agent registration skill: `https://chillaccount.com/.well-known/agent-skills/agent-registration/SKILL.md`
- Machine-readable API spec: `https://chillaccount.com/openapi.json`

## Requesting agent access
To request credentials for an autonomous agent, email `enquiry@chillaccount.com`
with your agent name, intended use, and required scopes (`blog:read`, `blog:write`).