# auth.md

> Machine-readable authentication guide for AI agents using the SpryTools API
> and the SpryTools MCP server.

## Audience

AI agents and automated clients that want to call the SpryTools utility APIs
(hashing, text stats, IBAN/email validation, DNS, currency, domain checks,
CiteReady GEO audits) via REST at `https://api.sprytools.com` or via the MCP
server at `https://api.sprytools.com/mcp` (Streamable HTTP).

## Authentication model

SpryTools uses **API keys**. OAuth 2.0 / OIDC is not currently offered — there
is no `/.well-known/oauth-authorization-server` and no
`/.well-known/oauth-protected-resource` metadata. Everything below is
self-serve and requires no human approval step.

## Register (free, self-serve)

```http
POST https://api.sprytools.com/v1/signup
Content-Type: application/json

{"email": "agent-operator@example.com"}
```

The response contains your API key (`key`). Store it securely — it cannot be
retrieved again later.

## Use the credential

Send the key on every request, REST and MCP alike:

- `x-api-key: <key>` (preferred), or
- `Authorization: Bearer <key>`

REST endpoints live under `https://api.sprytools.com/v1/<api>/...`; the MCP
endpoint is `POST https://api.sprytools.com/mcp` (JSON-RPC 2.0, stateless).
Each MCP `tools/call` counts once against the same plan quota as a REST call.

## Plans, quota and upgrades

- Free tier: 100 calls/day. Current paid plans: `GET https://api.sprytools.com/pricing`
- Upgrade: `POST https://api.sprytools.com/v1/checkout/session {"email","plan"}`
  returns a Stripe Checkout URL (a human completes payment).
- Manage or cancel a subscription: `POST https://api.sprytools.com/v1/portal {"email"}`

## Key lifecycle

- Claiming a paid plan after checkout rotates the key (the old key stops working).
- Quota-exceeded requests return HTTP 429 with the plan and limit in the body.

## Related discovery documents

- MCP server card: <https://sprytools.com/.well-known/mcp/server-card.json>
- API catalog (RFC 9727): <https://sprytools.com/.well-known/api-catalog>
- Agent skills index: <https://sprytools.com/.well-known/agent-skills/index.json>
- llms.txt: <https://sprytools.com/llms.txt>