# roimaxi.com auth.md — agent access

Most of what ROI Maximizer publishes is **public and needs no credentials**.
One capability writes data, and that one requires an OAuth 2.0 access token.

## Public — no authentication

- **MCP server:** https://roimaxi.com/api/mcp (streamable HTTP, stateless)
  - `get_company_overview`, `get_case_studies`, `get_booking_link`, `calculate_sales_roi`
  - Server card: https://roimaxi.com/.well-known/mcp/server-card.json
- **Markdown pages:** request any page with `Accept: text/markdown`
- **Site overview:** https://roimaxi.com/llms.txt
- **Discovery:** /.well-known/api-catalog, /.well-known/ai-catalog.json,
  /.well-known/agent-skills/index.json

## Authenticated — `submit_lead`

`submit_lead` records a contact request from someone who has explicitly asked to
be contacted. It requires a token so the channel can't be spammed, and so every
submission is attributable to a registered agent.

- **Scope:** `leads:submit`
- **Protected resource metadata:** https://roimaxi.com/.well-known/oauth-protected-resource (RFC 9728)
- **Authorization server metadata:** https://roimaxi.com/.well-known/oauth-authorization-server (RFC 8414)
- **Public keys:** https://roimaxi.com/.well-known/jwks.json (ES256)

Calling it without a valid token returns `401` with a `WWW-Authenticate` header
pointing at the resource metadata above.

## Registration

Open dynamic client registration (RFC 7591). No human approval step.

```bash
curl -X POST https://roimaxi.com/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name":"Your Agent","grant_types":["client_credentials"],"scope":"leads:submit"}'
```

Returns `client_id` and `client_secret`. Store the secret — it is not shown again.

## Getting a token

Grant type is `client_credentials`. There is no end user to consent, so there is
no authorization-code flow and no redirect URI.

```bash
curl -X POST https://roimaxi.com/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_ID" \
  -d "client_secret=YOUR_SECRET" \
  -d "scope=leads:submit"
```

Returns a Bearer access token, `ES256`-signed, valid for 1 hour, with audience
https://roimaxi.com/api/mcp. Verify it against the JWKS above.

## Calling the protected tool

```bash
curl -X POST https://roimaxi.com/api/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"submit_lead",
       "arguments":{"name":"...","email":"...","company":"...","message":"..."}}}'
```

## Rules for agents

- Only submit details a person has actually given you and asked you to pass on.
- One submission per person. Do not retry a successful call.
- Do not use this to advertise. Submissions are read by a human.

## Contact and revocation

Credentials are revoked by request: **moe@roimaxi.com**. Include your `client_id`.
Anything else: https://calendly.com/roimaxi/call