Docs / Reference / API keys

API keys

Create scoped API keys for programmatic access to the AskThis API, and the scopes each one can hold.

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.