API keys

Programmatic access to the AskThis API uses API keys — long-lived bearer tokens you create, scope and revoke from the dashboard under Settings → API keys, or over the API itself. To rotate a key, create a new one and revoke the old. Keys power the Public/Enterprise API surface.

API keys require a Pro plan or higher — the Free tier is dashboard-only. Requests are rate-limited by plan (per key): Pro 120/min, Business 600/min, Enterprise 3,000/min. Exceeding the limit returns 429 RATE_LIMITED with a Retry-After header; every response carries X-RateLimit-Limit and X-RateLimit-Remaining.

Authenticating

Send the key as a bearer token:

curl https://api.askthis.io/api/v1/sites \
  -H "Authorization: Bearer ak_xxxxxxxxxxxxxxxx"

Keys are shown once, at creation. We store only a hash — if you lose a key, revoke it and create a new one. Treat keys like passwords; anyone holding one can act within its scopes.

Scopes

Every key carries an explicit list of scopes, and each route requires a scope the key satisfies (default-deny). A :write scope implies its matching :read.

Scope	Grants
analytics:read	Read shares, AI clicks, questions, referrers
sites:read	List sites and install status
sites:write	Update site configuration
prompts:read	Read generated prompt templates
prompts:write	Create, edit, regenerate and import/export prompts
citations:read	Read Citation Monitor results
credits:read	Read credit balance and ledger
rules:read	Read prompt rules
rules:write	Create, edit and delete prompt rules
org:read	Read organization profile, plan and seats
*	All of the above (use sparingly)

Grant the narrowest set that does the job — a reporting integration needs only analytics:read.

Managing keys

# Create a key with two scopes → returns the plaintext ONCE
curl -X POST https://api.askthis.io/api/v1/keys \
  -H "Authorization: Bearer <session>" \
  -H "Content-Type: application/json" \
  -d '{ "scopes": ["analytics:read", "prompts:read"] }'

# List keys (masked — plaintext is never returned again)
curl https://api.askthis.io/api/v1/keys -H "Authorization: Bearer <session>"

# Revoke a key
curl -X DELETE https://api.askthis.io/api/v1/keys/<id> -H "Authorization: Bearer <session>"

Every create and revoke is written to the audit log. Rotate keys periodically and revoke any that leak.

Next: subscribe to webhooks so your systems hear about scans and low balances without polling.