# Auth.md: Finology Software Agent Authentication and Registration

Finology Software exposes a parity-verified federal student-loan calculation
engine to AI agents two ways:

- **Public REST API** (OpenAPI): `https://api.finology.tech`
- **MCP server** (Streamable HTTP): `https://mcp.finology.tech/mcp`

Both are **calc-only**. No client PII is read or accepted. All loan and
scenario numbers are supplied in the request, and every result is
provenance-stamped as coming from the Finology Software engine.

## 1. Get an API key

API access is key-gated. Request a key from Finology Software (contact
support@finology.tech). Keys are issued per account with a usage tier.

## 2. Authenticate

Send your key on every request:

- Preferred header: `X-Api-Key: <your-key>`
- Also accepted: `Authorization: Bearer <your-key>`

Verify your key and see your tier (no secrets returned):

```
GET https://api.finology.tech/v1/me
X-Api-Key: <your-key>
```

## 3. OAuth (authorization server)

For OAuth-based onboarding, the authorization server is Duende IdentityServer:

- Issuer / metadata: `https://identity.finology.tech/.well-known/openid-configuration`
- Protected-resource metadata (RFC 9728): `https://finology.tech/.well-known/oauth-protected-resource`
- Scopes: `finology.public-api`, `finology.mcp`

## 4. REST endpoints (OpenAPI: https://api.finology.tech/swagger)

- `POST /v1/projection` - one verified repayment projection
- `POST /v1/comparison` - compare scenarios, returns lowest-cost option
- `POST /v1/plan-eligibility` - eligible plans per loan
- `GET  /v1/plan-types` - accepted plan-type strings
- `GET  /v1/me` - identify the account and tier behind your key
- `GET  /health` - liveness

## 5. MCP tools (server-card: https://finology.tech/.well-known/mcp/server-card.json)

Connect an MCP client to `https://mcp.finology.tech/mcp` (Streamable HTTP, POST + GET) with the
`X-Api-Key` header. Tools:

- `run_projection` - one verified projection under one plan
- `compare_scenarios` - compare 2-10 scenarios, returns the cheapest
- `get_eligible_plans` - eligible plans per loan
- `get_plan_types` - accepted plan-type strings (call first if unsure)

## 6. Discovery index

- API catalog (RFC 9727): `https://finology.tech/.well-known/api-catalog`
- MCP server card: `https://finology.tech/.well-known/mcp/server-card.json`
- Agent Skills: `https://finology.tech/.well-known/agent-skills/index.json`
- llms.txt: `https://finology.tech/llms.txt`
- llms-full.txt: `https://finology.tech/llms-full.txt`