Authentication

Every REST API request needs an Octopost API key. Keys start with op_.

Where to get a key#

Open https://octopost.ink/dashboard/api/keys. That page shows:

• Your account key. It is ready to use as soon as you sign up. It is the same key the MCP server at https://octopost.ink/mcp takes.
• Keys you create. Click to create a named key (for example "CI" or "Blog cron"). You can give a key its own default account per network, so posts sent with it go out as that account. See Several accounts on one platform.

Both kinds of key work everywhere in the REST API and act on your real connected accounts. Test against a spare account if you don't want posts to go out.

Sending the key#

Use either header:

curl https://octopost.ink/api/posts \
  -H "Authorization: Bearer op_your_api_key_here"

curl https://octopost.ink/api/posts \
  -H "x-api-key: op_your_api_key_here"

If both are present, x-api-key wins.

What does not work on the REST API#

• Scoped keys. A key stored with a scope list (for example posts:read) is rejected by every REST endpoint, because Octopost does not check per-endpoint scopes. Keys created on the dashboard page have no scopes and get full access.
• OAuth access tokens (opat_...). These come from the MCP sign-in flow that clients like claude.ai and ChatGPT use. They only work on the MCP endpoint at https://octopost.ink/mcp, not on /api/*.
• Revoked or expired keys, and keys of a deactivated Octopost account.

Revoking and rotating keys#

You can have several keys at once. To rotate one:

1. Create a new key at https://octopost.ink/dashboard/api/keys.
2. Switch your app to the new key and check it works.
3. Revoke the old key on the same page. Revoking takes effect on the next request.

When authentication fails#

A request with no key at all (and no dashboard session) gets 401 with a hint:

{
  "error": "Unauthorized: no Octopost session cookie or API key on this request.",
  "fix": "Send your key as \"Authorization: Bearer op_...\" (or \"x-api-key: op_...\"). ...",
  "docs": "https://octopost.ink/docs/api/authentication.md"
}

A request with a key that starts with op_ but isn't valid (wrong, revoked, expired or scoped) gets a plain 401:

{ "error": "Unauthorized" }

Other checks on publishing#

A valid key isn't always enough to post:

• Creating or publishing posts needs an active plan. Without one, POST /api/posts and POST /api/posts/{id}/publish return 403 with "code": "trial_expired". Start or restart a plan at https://octopost.ink/dashboard/billing.
• POST /api/posts returns 403 until you verify your email address.

Keeping keys safe#

• Keep keys out of version control. Use environment variables or a secrets manager.
• Use a separate key per app or environment, so you can revoke one without breaking the others.
• If a key leaks, revoke it right away.