# TokenRoster authentication

## Summary

The TokenRoster public API (`/api/v1/*`), OpenAPI spec, and public MCP server require **no authentication**: no API key, no OAuth, no signup. All public endpoints are read-only GETs over HTTPS serving public registry data.

Authenticated programmatic access (uploading documents, running assessment reports) uses **personal access tokens** (PATs) — long-lived bearer tokens created in the web app — against the manage MCP endpoint.

## Supported methods

| Surface | Auth |
|---------|------|
| REST API `https://tokenroster.com/api/v1/*` | None |
| OpenAPI spec `https://tokenroster.com/openapi.json` | None |
| Public MCP server `https://tokenroster.com/api/mcp` (Streamable HTTP) | None |
| Manage MCP server `https://tokenroster.com/api/manage/mcp` (Streamable HTTP) | Bearer personal access token |
| Web app manage/billing flows | Browser session (Privy login) |

## Public walkthrough

No credential steps — a request works immediately:

```bash
# 1. Call any endpoint. No key, no header, no token.
curl "https://tokenroster.com/api/v1/stats"

# 2. You get JSON in a { data } envelope:
# { "data": { "total": 58, "founders": 120, ... } }

# 3. Errors are structured JSON with a hint:
# { "error": { "code": "not_found", "message": "...", "hint": "..." } }
```

MCP clients connect the same way — point a Streamable HTTP client at `https://tokenroster.com/api/mcp` with no auth configuration.

## Personal access tokens (manage MCP)

1. Sign in to the web app and create a token at https://tokenroster.com/manage/tokens. The token (`trpat_...`) is shown once — store it securely.
2. Connect a Streamable HTTP MCP client to `https://tokenroster.com/api/manage/mcp` with the header `Authorization: Bearer <token>`. Example (Claude Code):

```bash
claude mcp add --transport http tokenroster-manage "https://tokenroster.com/api/manage/mcp" \
  --header "Authorization: Bearer trpat_..."
```

3. Tools: `list_my_companies`, `list_my_documents`, `get_credits`, `upload_document`, `start_report_run`, `execute_report_run`, `get_report_run_status`, `get_report`. All actions are scoped to the token owner's companies; report runs consume report credits.
4. Revoke tokens any time at https://tokenroster.com/manage/tokens. Tokens do not expire.

Note: clients that cannot send custom headers (e.g. claude.ai web connectors, which require OAuth) are not supported yet.

## Rate limits

Fair-use limit of 120 requests/minute per client, communicated via `X-RateLimit-Limit` / `RateLimit-Policy` response headers. If you need sustained higher volume, get in touch via https://tokenroster.com/info.

## Write access

Programmatic write access (document upload, report runs) is available today via the manage MCP endpoint with a personal access token, as described above. Creating and editing listings still requires the TokenRoster web app (Privy-based login). OAuth 2.0 for API clients may ship later; this file will document the flow if it does.