One key, two interfaces

The REST API and the MCP server share a single credential and a single permission model. Get a key once and both work.

How do I get a CiteAgentic API key?

API keys are currently issued by our team rather than self-serve. Email support@citeagentic.com from the address on your account and tell us which scopes you need. Self-serve key management is being built; this page will change when it ships.

API and MCP access is a paid-plan capability. If your plan does not include it, every call returns tier_disallows_api — the API does not partially work on a plan without it.

How do I authenticate a request?

Send it as a bearer token:

Authorization: Bearer <your key>

That header is the same for POST /mcp and for every GET /api/v1/* endpoint.

Keys are stored as a SHA-256 hash, never in plain text. That means we cannot show you a key again after it is issued, and we cannot recover a lost one — a lost key is revoked and replaced.

What scopes are available?

A key carries a list of scopes, and each tool or endpoint declares the one it needs. Read, write and run are deliberately separate, because running work spends credits and the other two do not.

Scope	Grants
`read:sites`	Site list, portfolio summary, site brief
`read:visibility`	Visibility scores and history
`read:audits`	Audit scores and findings
`read:prompts`	Prompt list and per-prompt detail
`read:competitors`	Competitor list and gap analysis
`read:recommendations`	The recommendation queue, including fix prompts
`read:content`	Content opportunities and drafts
`read:voice`	Voice profile, review themes, buyer criteria
`write:prompts`	Generate and refine prompts
`write:competitors`	Add a competitor
`write:content`	Generate a content draft
`run:visibility`	Start a visibility scan
`run:audits`	Start an audit scan

Ask for the narrowest set that does the job. A key that only reports on visibility does not need run: scopes, and a scan started by mistake spends credits that a read-only key could never have spent.

What data can an API key reach?

A key resolves to the user who owns it, and sees exactly what that user sees: the sites they own, plus any they collaborate on. This is enforced by row-level security in the database, not only by the route handler, so a bug in a route cannot leak another tenant's data.

Quotas are the plan's quotas. Prompts, competitors and drafts created through the API count against the same limits as the UI. The API is another way into the same account, not a way around it.

Why was my API call rejected?

There are four rejections, and they mean different things: a bad credential, a plan without API access, or a key missing the scope this call needs.

Response	Meaning
`401 missing_bearer_token`	No `Authorization: Bearer` header was sent
`401 invalid_api_key`	The key does not match any active key — check for a typo, or it was revoked
`403 tier_disallows_api`	The key is valid, but the account's plan does not include API access
`403 insufficient_scope`	The key is valid and the plan allows API access, but this key lacks the scope this call needs

The distinction matters when you are debugging: invalid_api_key is a credential problem, tier_disallows_api is a billing problem, and insufficient_scope means ask us to reissue with a wider scope list.

Can I see what a key has done?

Every call is recorded against the key that made it, including the tool or endpoint name and whether it succeeded. If you hand a key to an automation, its activity is attributable to that key rather than blended into your own.