# auth.md

Base URL: `https://grokbot.publiexpert.com`

This host exposes an agent-native MCP server at `https://grokbot.publiexpert.com/mcp`. All tools are
public and read-only, so anonymous access works today; an optional OAuth 2.1
path is described below for agents that prefer to present an identity.

## Flow

1. **Discover the protected resource (PRM)** — `GET https://grokbot.publiexpert.com/.well-known/oauth-protected-resource`.
   It returns `resource`, `authorization_servers`, `scopes_supported` and
   `bearer_methods_supported: ["header"]` — send tokens in the
   `Authorization: Bearer <token>` HTTP header only (no query or body).
2. **Discover the authorization server (AS)** — `GET https://grokbot.publiexpert.com/.well-known/oauth-authorization-server`
   (or `https://grokbot.publiexpert.com/.well-known/openid-configuration`). Its `issuer` matches the
   `authorization_servers` entry in the PRM. The `agent_auth` block lists
   `register_uri`, `identity_endpoint`, `claim_uri` and `revocation_uri`.
3. **Register** — `POST` to the `register_uri` (RFC 7591 dynamic client
   registration) with your `client_name` and `redirect_uris`. Anonymous agents
   may skip registration entirely.
4. **Claim an identity** — `POST` to the `claim_uri` with an identity assertion
   (`urn:ietf:params:oauth:token-type:id-jag` or `verified_email`) to bind your
   agent to a known operator. Optional for anonymous use.
5. **Token** — `POST` to the `token_endpoint` to obtain an `access_token`
   (`credential_types_supported: ["access_token"]`).
6. **Use /mcp** — call the MCP Streamable HTTP endpoint:

```bash
curl -s https://grokbot.publiexpert.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'authorization: Bearer <access_token>' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

   The `authorization` header is optional while the tools remain public.
7. **Revoke** — `POST` to the `revocation_uri` (RFC 7009) with the token to
   invalidate it when your session ends.

## Tools

| Tool | What it does | Side effects |
| --- | --- | --- |
| `get_service_overview` | Service offer, what GrokBot is, the 3-step process | read-only |
| `search_faq` | Search published FAQ and objection answers | read-only |
| `list_use_cases` | Automation use cases, ideal niches, industries | read-only |
| `get_contact_channels` | Email, WhatsApp, US phone, booking URL | read-only |
| `prepare_booking_link` | Builds a pre-filled booking link | no booking is created |

Booking is only confirmed when a human opens https://cita.publiexpert.com/.

## Policy

- Identify your client with a descriptive `User-Agent`.
- Keep request volume reasonable; excessive traffic may be rate-limited.
- Questions or authenticated access requests: nathan@publiexpert.com / support@publiexpert.com.