# Agent authentication — Agora

MCP endpoint: `https://agora-mcp.hefes.net/mcp` (Streamable HTTP, protocol 2025-06-18)

| Document | URL |
|---|---|
| Protected resource (RFC 9728) | https://agora-mcp.hefes.net/.well-known/oauth-protected-resource |
| Authorization server (RFC 8414) | https://agora-mcp.hefes.net/.well-known/oauth-authorization-server |
| Public keys | https://agora-mcp.hefes.net/oauth/jwks |

## Read tools need no credential at all

`search_businesses`, `get_business` and `get_attestation` work anonymously,
rate-limited per IP. Evaluate the registry before registering anything.

## Register in one call — no forms, no email

Dynamic client registration (RFC 7591) is open:

```sh
curl -X POST https://agora-mcp.hefes.net/oauth/register \
  -H 'content-type: application/json' \
  -d '{"client_name":"My Assistant","contacts":["you@example.com"]}'
```

You get a `client_id` and a `client_secret`. **The secret is shown once.**

Then exchange them for a token (client_credentials — see below for why that is the
only grant):

```sh
curl -X POST https://agora-mcp.hefes.net/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H 'content-type: application/json' \
  -d '{"grant_type":"client_credentials","scope":"agora:read"}'
```

```http
Authorization: Bearer <access_token>
```

Tokens are ES256 JWTs, audience `https://agora-mcp.hefes.net/mcp`, valid one hour. Verify them against
`https://agora-mcp.hefes.net/oauth/jwks` if you proxy them.

## Scopes

| Scope | Grants | How to get it |
|---|---|---|
| `agora:read` | search, get_business, get_attestation, at a raised rate limit | self-service, instantly |
| `agora:act` | contact_business, request_quote, get_thread | operator approval |

**Why `agora:act` is gated.** Those tools relay messages to a shop owner's
personal WhatsApp or Telegram. The reason businesses tolerate being on Agora is
that we do not let strangers message them, so act is approved by a human after a
short look at what you are building. Register first, then email
**agents@hefes.net** with your `client_id`, the product, expected volume, and who
the end users are. Requesting `agora:act` at registration is recorded but never
granted automatically.

## Why client_credentials is the only grant

There is no `authorization_endpoint` and no `/.well-known/openid-configuration`,
deliberately. An agent calling Agora acts for ITS OWN user, not for an Agora
account holder — businesses have no logins at all (they prove a messaging channel
instead), and the staff console is unrelated. An authorization-code flow would
render a consent screen with nobody to consent. Do not attempt one.

## Legacy API keys

Operator-issued keys of the form `prefix.secret` still work, presented the same
way or as `X-Agora-Key`. New integrations should use OAuth: it is self-service,
scoped, and you can revoke yourself.

## Rules attached to every credential

- Every action call is audited, per client.
- Revocation is immediate. Tokens are JWTs, but the client row is re-checked on
  every request — a revoked client stops working on its next call, not when its
  token expires. Revoke your own: `POST https://agora-mcp.hefes.net/oauth/revoke` with your client
  credentials.
- Rate limits are enforced server-side and persist across restarts.
- Do not present `basic` or `unverified` listings to users as "verified". The
  tier semantics are documented at https://agora.hefes.net/llms.txt — misrepresenting them is
  grounds for revocation.