API keys & scopes

Create, scope, and revoke API keys, and understand per-plan rate limits.

API keys are long-lived bearer tokens that power the Public/Enterprise API. Create, scope, and revoke them from the dashboard under Settings → API keys, or over the API. A key is shown once at creation — only a hash is stored, so save it somewhere safe.

Keys require the Pro plan or higher (the Free tier is dashboard-only).

Scope a key to least privilege

Every key carries an explicit list of scopes, and every route requires a satisfied scope (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, 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, delete prompt rules
`org:read`	Read organization profile, plan, and seats
`*`	All of the above (use sparingly)

Two endpoints reject keys on purpose

Because every route is default-deny, a couple of endpoints return 403 INSUFFICIENT_SCOPE even for an all-scopes (*) key — this is expected, not a broken key:

GET /api/v1/me is a dashboard/session endpoint (who am I), so it’s never key-accessible. Read your org from GET /api/v1/orgs/:id instead.
GET /api/v1/sites/:id/config is the public, keyless widget config (the same edge-cached payload the widget fetches). Call it without an Authorization header and it returns 200; sending a key trips default-deny. Only the config write (PUT /api/v1/sites/:id/config, scope sites:write) is authenticated.

So don’t blanket-attach your key to every request — the public config read is the one call you make keyless.

Manage keys over the API

Key management uses your dashboard session, not an ak_ key:

# 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>"

To rotate a key, create a new one and revoke the old. Every create and revoke is written to your audit log.

Rate limits by plan

Keys are rate-limited per plan, per key:

Plan	Limit
Pro	120 requests/min
Business	600 requests/min
Enterprise	3,000 requests/min

Exceeding the limit returns 429 RATE_LIMITED with a Retry-After header; every response carries X-RateLimit-Limit and X-RateLimit-Remaining.

Full reference

The complete keys and scopes reference is in the developer docs: API keys.