# 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, and a sandbox key is self-serve with no signup and no
human in the loop:

```
POST https://api.finology.tech/v1/keys/sandbox
Content-Type: application/json

{"email": "you@example.com"}
```

The key comes back immediately: 100 calls per month, valid 30 days, accepted by
both the REST API and the MCP server.

Production access is self-serve too. Subscribe at
https://buy.stripe.com/28E4gy3LHf188KYd5kaZi01 ($499/month, 100,000 calls per
month, cancel any time) and the production key arrives by email the moment
payment clears. It is shown once and never stored, so save it when it lands.
Manage or cancel at https://billing.stripe.com/p/login/dRmcN46XTg5cd1eaXcaZi00.

Use of the API and the MCP server is governed by the API and MCP Terms of Service:
https://finology.tech/api-terms/. Requesting a key or sending a request is acceptance.

## 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. There is no OAuth flow on these surfaces

Both the REST API and the MCP server accept **API keys only**. They do not
validate OAuth or OIDC access tokens, so do not attempt an authorization-code
or client-credentials exchange against them: a token presented as
`Authorization: Bearer` is read as an API key and will be rejected.

`https://identity.finology.tech` is the sign-in service for the Finology
Software web application. It is not an authorization server for the API or the
MCP server.

- Protected-resource metadata (RFC 9728): `https://finology.tech/.well-known/oauth-protected-resource`
  (identifies the resource and points back here; it advertises no authorization server, because there is none)

## 4. REST endpoints (reference: https://finology.tech/developers/)

- `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`