Skip to main content
Ranksify
Browse documentation

API & automation

API keys

Every machine-to-machine door into Ranksify — the REST API, log ingest and the MCP server — is opened by an rk_ key. Keys belong to a workspace, not to a person, and carry their own scopes and rate limit.

Create a key

  1. Open Settings and go to API keys. Managing keys requires an admin role.
  2. Name it after the thing that will hold it — the CI job, the Worker, the assistant.
  3. Give it the narrowest scope set that does the job.
  4. Copy the key immediately.
The raw key is returned once, at creation, and is never retrievable again. Ranksify stores a SHA-256 hash plus a short display prefix, so the list can identify a key without being able to reproduce it. Lose it and the fix is to revoke and mint a new one.

Scopes

ScopeOpens
readThe public REST API — see the API reference.
ingestThe log-ingest endpoint, for pushing server logs and edge forwarder output. See crawler logs.
mcpThe MCP server read tools, for AI assistants.
mcp:writeMCP write tools on top of mcp — create/update prompts, content drafts, publish to a connected CMS, and run a site audit. Additive: tick mcp and mcp:write together. See MCP write tools. Prefer a dedicated key; do not hand an mcp:write credential to a client that only needs metrics.

A key presented to an endpoint it lacks the scope for is refused with a 403 naming the missing scope — it is not silently downgraded.

Read and MCP keys may cover the whole workspace or one brand (called a project in the API). An ingest key must be limited to one brand; the brand’s projectId in the ingest endpoint must match it.

Using a key

Authorization: Bearer rk_your_key_here

A malformed or unknown key returns 401. Every key has a workspace ceiling and may have a narrower brand ceiling. Asking outside either returns 404 rather than 403 — the API does not confirm the existence of things you cannot see.

Rate limits

Each key has its own requests-per-minute limit, set when you create it. Exceeding it returns a rate-limited error with a Retry-After header. Because the limit is per key, one noisy integration cannot exhaust another's budget — which is the practical argument for one key per consumer rather than one shared key.

Plan requirement

API access and the MCP server are paid-plan features. This is enforced on every request, not only at creation time: if a workspace lapses or downgrades, its existing keys stop working too. See pricing.

Rotating a key

Create the replacement first, deploy it, confirm the old key has stopped being used, then revoke it. Revocation takes effect immediately, so revoking first means downtime.