# Auth.md

How an agent gets access to ModelSpec.

Three ways in: keyed CLI, MCP and HTTP API. Machine data access needs a ModelSpec API key; only human lookup is free. No data download or local decision cache.

```sh
uvx --from modelspec-dev modelspec
pipx install modelspec-dev
pip install modelspec-dev
```

pip install modelspec is an unrelated project. Use modelspec-dev.
Guide: https://modelspec.dev/agents.md. Pricing and keys: https://modelspec.dev/pricing/.

Buy a plan or pack at https://modelspec.dev/pricing/. Stripe hosts Checkout; claim your key at the success link. Checkout availability is shown on the page. For access, volume or invoicing, contact sales@modelspec.dev. Store a key with modelspec auth set, or set MODELSPEC_API_KEY; the environment wins.

The decide, legacy v1 rank, and policy-check APIs live at `https://api.modelspec.dev`. Present a key with `Authorization: Bearer <key>` or `X-API-Key`. A key is never read from the query string.

## What is live

Hosted API data tools need an API key. Buy a plan or pack at https://modelspec.dev/pricing/. Stripe hosts Checkout; claim your key at the success link.

### Hosted API data tools (key required)

- `POST /v1/decide` — downselect from a decision spec.
- `POST /v1/compare` — compare a decision spec across snapshots.
- `POST /v1/compare-models` — compare named models' facts in caller order.
- `POST /v1/rank` (legacy v1) — retired fixed-benchmark ranking, for existing callers.
- `POST /v1/policy-check` — licence, origin, data handling per model and platform. Checks that need the private determination store stay `undetermined` with `why: tier`. That is not a pass.
- `GET /v1/vocabulary` — valid facet ids and display definitions.

`GET /v1/health` reports the deploy pin; it carries no model data.
The free decide page uses the human browser visit gate: a Turnstile-verified visit token admits decide and vocabulary for its bound visitor and site origin. Machine callers use an API key.

### MCP

MCP `https://api.modelspec.dev/mcp` has 8 tools: decide, rank, model_info, list_use_cases, policy_check, compare_models, vocab, feedback.
MCP data tools rank, policy_check, decide, compare_models, vocab, model_info and list_use_cases require `Authorization: Bearer <key>`. Feedback stays keyless; it carries no model data.

### Sandbox (`test_` keys)

Any key beginning `test_` is unlimited and is answered from the sandbox. No signup, no key store, no published export. Legacy v1 rank only; `POST /v1/policy-check` with a `test_` key is `400 sandbox_not_available`. Rows are synthetic, from the real scorer, not live catalogue data.

## Billing and payments

Billing is enabled. Buy a monthly plan or a prepaid credit pack at https://modelspec.dev/pricing/. Stripe hosts Checkout. After payment, claim your API key at the Checkout success link. Claim and rotation remain available for earlier purchases. See `docs/billing.md`.

OpenAPI: https://modelspec.dev/openapi.yaml
Human docs: https://github.com/turbobeest/modelspec/blob/main/docs/api.md