# auth.md

GammaPredict agent authentication and registration guide.

## Audience

AI agents and automated clients that want to use GammaPredict public discovery APIs, MCP tools, and editorial content.

## Summary

GammaPredict is an **editorial comparison directory**. Public read endpoints (`/api/news`, `/api/health`, `/mcp` tools, static pages) do **not** require user login. Agents may register anonymously to receive a public-read bearer token for consistent client identification.

## Protected resource metadata

- Resource: `https://gammapredict.com/`
- Metadata: `https://gammapredict.com/.well-known/oauth-protected-resource`
- Authorization server: `https://gammapredict.com`
- AS metadata: `https://gammapredict.com/.well-known/oauth-authorization-server`
- OIDC discovery: `https://gammapredict.com/.well-known/openid-configuration`

## Registration

1. `GET` or `POST` `https://gammapredict.com/agent/register`
2. Provide an optional `client_name` and requested scopes from `read:public`, `read:news`, `read:platforms`, `tools:mcp`
3. Receive a client id for anonymous public-read access
4. Claim a bearer token at `https://gammapredict.com/agent/claim`

Anonymous identity is supported. No email verification is required for public read scopes.

## Using credentials

Send the bearer token when present:

```http
Authorization: Bearer <token>
```

If no token is supplied, public GET endpoints still succeed. Tokens exist so agents can identify themselves and stay aligned with Auth.md discovery.

## Scopes

| Scope | Access |
|-------|--------|
| `read:public` | Health, catalogs, static discovery docs |
| `read:news` | `/api/news` |
| `read:platforms` | Platform list / match helpers via MCP |
| `tools:mcp` | MCP tool calls at `/mcp` |

## Service docs

- API overview: `https://gammapredict.com/docs/api.md`
- OpenAPI: `https://gammapredict.com/openapi.yaml`
- MCP card: `https://gammapredict.com/.well-known/mcp/server-card.json`