Authentication

Every API request needs an Authorization header in the form:

Authorization: Bearer pm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

That's it. No per-request signing, no JWT exchange, no challenge-response.

Generating an API key

/app/settings/api → Create key. Name it (helps when you have several), choose a workspace if you have multiple, click create.

The key is shown once — copy it into your env file or secret manager immediately. We store only a hashed version on our side; you cannot view the plaintext again.

If you lose a key, rotate it (see below) and update your client. We don't recover keys.

Scopes

Each key has read and write scopes:

posts:read — list and read post details
posts:write — create, update, delete posts
accounts:read — list connected social accounts
analytics:read — read post-level metrics

By default, new keys are issued with all four scopes. You can restrict scopes when you create the key — useful if you're giving a key to a read-only integration.

Workspace scoping

Each key belongs to a single workspace. If you're on a Pro plan with multiple workspaces, each one needs its own key — they don't cross-cut.

This is a deliberate boundary. A key generated in workspace A cannot see, list, or post to social accounts in workspace B.

Rotating

/app/settings/api → find the key → Rotate. The old key is invalidated; a new one is issued. You see the new plaintext once.

Best practice: rotate keys every 90 days, or immediately if you suspect a leak (committed to a public repo, copied in a screenshot, etc.).

Revoking

Same screen → Revoke. The key stops working immediately; revocation is irreversible. No grace period, so be sure before you hit it.

Bearer prefix

Every Post Mate key starts with the prefix pm_. The next segment distinguishes the environment:

pm_live_… — production keys, ~32 chars after the prefix
pm_test_… — sandbox keys, same format, only work against the sandbox API (not generally available — ask if you need one)

The prefix lets git-secret scanners and IDE plugins detect a leaked Post Mate key the same way they detect Stripe and OpenAI keys.

Rate limits per key

Each key gets its own 60 req/min sliding-window budget. If you have multiple keys, they don't share — useful for separating a publishing service from an analytics service.

When you hit the limit, we return 429 with:

Retry-After: 12

The header tells you how many seconds to wait. Respect it; the backoff is exponential if you keep hammering after a 429.