Public API

Authentication and permissions

API key, MCP key, OAuth token: what each one is for, how to create it, and what the scopes mean.

The three credentials

Type	Prefix	Where you use it	Where it comes from
API key	`psty_…`	REST API and the command-line tool	Automations → Developers
MCP key	`psty_mcp_…`	MCP server, for chat clients	Automations → Developers
OAuth token	`pos_…`	When an app acts on someone else's behalf	At the end of the OAuth flow

REST keys and MCP keys are not interchangeable

The MCP server deliberately rejects REST keys that start with psty_ and explains why. If a chat client cannot connect, this is the most common reason.

The API key

You create the key in Postemi, on the Automations → Developers page. You don't need to write to us, and there's no approval process. The key is shown once, at the moment you create it. You cannot retrieve it later.

Every request sends the key in the Authorization header. The key is the header's entire value:

curl https://api.posty.hu/public/v1/integrations \
  -H "Authorization: psty_your_key"

An OAuth token, however, has a Bearer prefix:

curl https://api.posty.hu/public/v1/integrations \
  -H "Authorization: Bearer pos_your_token"

Permissions

You can restrict the key: only allow the operations it actually needs. These are the scopes, and the https://api.posty.hu/public/v1/status response lists them too.

Scope	What it allows
`posts:read`	Read the calendar and posts.
`posts:draft`	Create, edit, and delete drafts.
`posts:publish`	Schedule and publish immediately, and move a post out of draft.
`channels:read`	Read channels, groups, and settings schemas.
`channels:write`	Start connecting a channel.
`media:write`	Upload to the media library.
`analytics:read`	Read statistics.

MCP has two scopes: mcp:read and mcp:write. We accept them for compatibility, but they do not limit what an MCP connection can do: the signed-in person's role in the workspace decides that.

Give as little as possible

An agent that creates drafts only needs posts:read and posts:draft. Then if something goes wrong, the worst that can happen is an unnecessary draft, not a post that went out to a real audience.

Choosing a workspace

If a key belongs to more than one workspace, the showorg header selects which one the call applies to:

curl https://api.posty.hu/public/v1/integrations \
  -H "Authorization: psty_your_key" \
  -H "showorg: <workspace-id>"

401 and 403

Code	What it means	What to do
401	The credential is missing, wrong, expired, or has been revoked.	Check that the key is the entire Authorization header value, with no Bearer. Also check that you haven't rotated it in the meantime.
403	Authentication is fine, but the permission is not enough.	The response names the missing scope and the key owner's current role. Check both.

A 403 is usually about the user

The permission a key carries moves with its owner's current role. If someone is demoted or removed from the workspace, their key immediately has only as much access as they do. When a key that worked yesterday returns a 403 today, it is almost always this.

Key management

Put it in an environment variable or a secret manager, not in the code, and not in version control.
If it ended up somewhere it shouldn't, rotate it on the Settings → Developers page. Rotation is immediate. The old key gets a 401 on the next call.
You don't even need to copy a key for the command-line tool: posty auth:login stores the credential on your machine. See the CLI authentication page.
Never send us the API key by email. We don't need it.

Is something missing from this page? Email [email protected] or use the form on the Help page.