Authentication

Everything works anonymously — but a free API key gives you your own daily quota (instead of sharing the per-IP one), metered usage, and a stable identity for your integration.

Get a key

Or from the terminal:

bash

curl -X POST https://www.stipple.sh/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com"}'

# → { "api_key": "stp_...", "key_id": "key_...", "daily_limit": 50 }

The key is shown once and never stored in plaintext on our side — only a hash. Lose it, mint a new one (up to 5 per email).

Use it

Send the key on every request — REST and MCP alike — as a Bearer token:

bash

curl -X POST https://www.stipple.sh/v1/verify-references \
  -H "Authorization: Bearer stp_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf"}'

A presented-but-invalid key returns 401 — it never silently falls back to the anonymous quota, so typos and revocations surface immediately.

Quotas

Parameter	Type	Description
Anonymous	per IP	20 documents/day, shared by everyone behind that IP.
API key	per key	50 documents/day on your own quota — IP-independent (important for hosted agents and CI).
Burst guard	both	~10 requests at once, refilling ~30/min.

Check your usage

Usage is metered by the same counters that enforce the quota, so what you read is exactly what's enforced:

bash

curl https://www.stipple.sh/v1/usage -H "Authorization: Bearer stp_..."

# → {
#     "key_id": "key_…",
#     "daily_limit": 50,
#     "today": { "used": 12, "remaining": 38 },
#     "days": [ { "day": "20260612", "count": 12 }, ... ]
#   }

MCP

MCP clients that support custom headers can send the same Authorization header on the server connection — the tools then meter against your key instead of your egress IP. See MCP integration.

Good to know

Keys are free while the service is in preview; metering exists so future paid tiers have honest history.
Need a higher limit for a real integration? Email us — limits are per key and adjustable.
To revoke a key today, email us; self-serve revocation ships with the dashboard.