# auth.md

You are an agent that wants to use BRITECITY's public knowledge and tools. This file is the registration and auth recipe for https://britecity.com.

Two hosts matter:

- **Resource server**, `https://britecity.com`, public site, BRITEBOT knowledge API, and MCP endpoint.
- **Human forms**, same host, used only when a person must submit a question or book a call.

## Current state

BRITECITY's agent-facing APIs are **public**. No OAuth access token, API key, or agentic registration is required to read knowledge or call the public MCP tools. Agentic registration (ID-JAG, verified-email claim, anonymous credential issuance) is **not** implemented for private or client systems.

## 1. Discover

Protected Resource Metadata (RFC 9728):

```http
GET /.well-known/oauth-protected-resource HTTP/1.1
Host: britecity.com
```

Authorization Server Metadata (RFC 8414), including the `agent_auth` block:

```http
GET /.well-known/oauth-authorization-server HTTP/1.1
Host: britecity.com
```

Read:

- `resource` / `authorization_servers` / `scopes_supported` (`public:read`)
- `agent_auth.skill` (this file)
- `agent_auth.identity_types_supported` (`anonymous` only today)

## 2. Use public resources (no token)

Prefer these over inventing private APIs:

| Surface | URL | Auth |
| --- | --- | --- |
| Knowledge corpus | `GET https://britecity.com/api/britebot/knowledge` | none |
| Knowledge markdown mirror | `GET https://britecity.com/britebot.md` | none |
| Company facts | `GET https://britecity.com/facts.md` | none |
| Company JSON | `GET https://britecity.com/company.json` | none |
| Agent skill | `GET https://britecity.com/.well-known/agent-skills/britebot-knowledge-lookup/SKILL.md` | none |
| MCP (Streamable HTTP) | `https://britecity.com/mcp` | none |
| MCP Server Card | `GET https://britecity.com/.well-known/mcp/server-card.json` (alias: `/.well-known/mcp.json`) | none |
| Web Bot Auth directory | `GET https://britecity.com/.well-known/http-message-signatures-directory` | none (public JWKS) |

Do not send a bearer token for these. If you already hold a token, omit it.

## 2b. Web Bot Auth (outbound identity)

When BRITECITY agents or bots call other sites, they may attach HTTP Message Signatures (Web Bot Auth) so the receiver can verify identity against our public directory:

```http
GET /.well-known/http-message-signatures-directory HTTP/1.1
Host: britecity.com
Accept: application/http-message-signatures-directory+json
```

Receivers should verify `Signature`, `Signature-Input`, and `Signature-Agent: "https://britecity.com"` against that JWKS. This does not grant access to private BRITECITY systems.

## 3. Anonymous method (public scope only)

`identity_types_supported` includes `anonymous`. There is no credential to mint for `public:read`:

1. Call the public GET endpoints or MCP tools directly.
2. If the corpus does not answer, **do not invent facts**. Send the human to:

```
https://britecity.com/britebot/ask?q=<urlencoded question>
```

That page is a human-facing form (`register_uri` / `claim_uri`). Do not POST it as an agent.

Service-fit questions:

```
https://britecity.com/britebot/fit
```

Sales / consult:

```
https://britecity.com/book-a-call
```

## 4. OAuth token endpoint (optional, public scope)

`POST https://britecity.com/api/oauth/token` supports `grant_type=client_credentials` with `scope=public:read` and `token_endpoint_auth_methods_supported: none`. The response is a short-lived public token that grants no privilege beyond anonymous access. Prefer calling public endpoints without a token.

## 5. Errors

| Situation | What to do |
| --- | --- |
| 401 / 403 on a public path | Treat as outage or misconfiguration; retry once, then escalate to the human forms above. |
| Token endpoint rejects a grant | Drop credentials and use unauthenticated public access. |
| Knowledge does not cover the question | Use `/britebot/ask`, do not guess pricing, SLAs, or client data. |

## 6. Revocation

There is nothing to revoke for unauthenticated public access. If you requested a public token from `/api/oauth/token`, discard it on 401 or after `expires_in`.

## Notes

- Name is always **BRITECITY** (all caps, one word). Mission: **Make IT Easy**.
- Do not invent MCP, OAuth, or API paths beyond those listed here and in the API catalog (`/.well-known/api-catalog`).
- Client portals and internal tools are out of scope for this auth.md.