Authentication

Every request to the Post-EZ public API is authenticated with a bearer token. Tokens are created from the in-app dashboard under Settings -> API keys and are scoped to the operations they can perform. We never echo the secret back after creation, so write it down somewhere your secrets manager can read.

Token shape

Plaintext keys look like pz_ followed by a 43-character base64url string. The pz_ prefix is there so the secret is visibly distinct from anything else floating around in your environment, and so log scrubbers can pattern-match on it.

pz_aaaaaaaa_bbbbbbbb_cccccccc_dddddddd_ee

We only store a SHA-256 hash of the key. If you lose it, mint a new one — there's no recovery flow.

Sending the token

Set the standard Authorization header on every request. Anything missing the header (or sending a malformed token) gets a 401.

curl -X GET https://postez.app/api/v1/accounts \
  -H "Authorization: Bearer pz_YOUR_KEY_HERE"

Scopes

Each key carries an explicit set of scopes. The endpoint will return 403 if the key doesn't carry the scope it needs. The current scope catalog:

• publish — POST /api/v1/publish (immediate publish)
• scheduled.read — GET /api/v1/scheduled-posts
• scheduled.write — POST /api/v1/scheduled-posts
• accounts.read — GET /api/v1/accounts

Pick the narrowest set that does the job. A CI cron that only schedules content should not also carry publish.

Creating a key

1. Open Settings -> API keys in your Post-EZ dashboard.
2. Click New key, give it a name (e.g. "Zapier prod"), and tick the scopes it needs.
3. Copy the plaintext key into your secrets store. We show it once.
4. Optionally set an expiry — keys with expires_at in the past are rejected as expired.

You can revoke any key from the same screen. Revoked keys come back as 401 immediately on the next request — we don't cache verifications.

Error shape

Every error response uses the same envelope so you can branch on error without parsing strings:

{ "ok": false, "error": "missing_scope" }

Common codes you'll hit while wiring auth: missing (no header), malformed (header didn't start with Bearer pz_), not_found (hash didn't match a row), revoked, expired, missing_scope. The HTTP status mirrors the cause — 401 for "we couldn't identify you", 403 for "we know who you are, you can't do that".