Authentication
How to authenticate against api.misar.io/seo — developer API keys, session cookies, and the auth modes MisarSEO supports.
Every api.misar.io/seo/* endpoint resolves a caller through the same chain. For programmatic use, that means one thing: a bearer API key.
Developer API keys
Keys are available today
Create a key from your MisarSEO account and use it immediately. Keys are prefixed mseo_ and are stored hashed — the raw value is shown once, at creation.
Authorization: Bearer mseo_your_key_hereKeys are the auth mode used by both the TypeScript SDK and the stdio MCP server. Anything running outside a browser should use one.
Manage keys
Key management runs on the session cookie, not on a bearer key — you cannot mint a new key with an existing key.
/api/keysList your keys. Secrets are never returned.
{ "keys": [{ "id": "key_01J…", "name": "ci-pipeline", "createdAt": "2026-07-02T11:04:00.000Z" }] }/api/keysCreate a key. The raw secret is returned once — store it immediately.
Request body
namestringbodyrequiredA label for the key. Must be non-blank.
Response fields
idstringKey id, used to delete it later.
namestringThe label you supplied.
keystringThe raw mseo_… secret. Shown once and never again.
curl -X POST https://api.misar.io/seo/api/keys \
-H "Content-Type: application/json" \
-H "Cookie: <session>" \
-d '{ "name": "ci-pipeline" }'{
"id": "key_01JABCDEF",
"name": "ci-pipeline",
"key": "mseo_live_9f2c…"
}/api/keysDelete a key by id. This is a hard delete, not a soft revoke — the row is removed.
Query parameters
idstringqueryrequiredThe key id from GET /api/keys.
curl -X DELETE "https://api.misar.io/seo/api/keys?id=key_01JABCDEF" \
-H "Cookie: <session>"{ "ok": true }Status codes
| Code | Meaning |
|---|---|
200 | Listed or deleted |
201 | Created — read key now |
400 | DELETE without an id |
401 | { "error": "unauthorized" } — no session cookie |
404 | { "error": "not found or unauthorized" } |
422 | { "error": "name required" } |
Key management is not rate limited.
Auth resolution order
A request is resolved through these modes in order. The first that claims the request wins.
Local no-auth
A development-only mode that injects a local admin context. Never enabled in production.
Bearer API key
A token beginning mseo_ is looked up against the hashed key store. Any other bearer value is compared against the deployment-wide service key, when one is configured.
Hosted session
The browser session cookie, used by the MisarSEO dashboard itself.
Cloudflare Access
A verified Access JWT, for self-hosted deployments sitting behind Cloudflare Access.
An unresolved request returns 401 with code UNAUTHENTICATED.
Project scoping
Almost every endpoint takes a projectId, and every one of those re-checks that the project belongs to the caller's organization.
A project you do not own returns 404, not 403
Cross-tenant access is reported as 404 NOT_FOUND with the message Project not found, deliberately — the API never confirms that another organization's project id exists.
One endpoint is unauthenticated
POST /seo/citations takes no credentials
The AI citation checker does not resolve a caller, does not take a projectId, and is not rate limited. Treat it as a public utility endpoint and do not send anything sensitive to it. Every other /seo/* endpoint requires authentication.