Developers

Authentication

API keys are minted per organization. Anyone holding a key can act on behalf of that organization within the scopes the key was issued for.

Token format

text

pml_live_<lookupId>_<secret>
└────┬────┘ └────┬────┘ └───┬────┘
     │           │          └─ 32 base62 chars: the secret half. Never stored
     │           │             in plaintext; we keep only a SHA-256 hash.
     │           └─────────── 12 base62 chars: the lookup half. Indexed in the
     │                        database; used to find the row before verification.
     └─────────────────────── Static prefix. Lets us (and secret-scanners) tell at
                              a glance that a leaked string is a postme.live key.

Total entropy in the secret half is ≈190 bits. We do not need bcrypt or argon2; those exist to defend low-entropy passwords, and for cryptographically-random API keys a single SHA-256 round is the standard.

Sending the key

Use the standard HTTP Authorization header with the Bearer scheme:

http

GET /api/v1/channels HTTP/1.1
Host: postme.live
Authorization: Bearer pml_live_AbCdEf123456_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Creating, rotating, revoking

Workspace owners and admins manage keys at Settings → Developers:

Create. Give the key a human-readable name and pick an expiry (1 day / 7 days / 30 days / 90 days / never). The full token is shown once. Copy it then.
Rotate. There is no in-place rotation. Create a new key, swap your config, then revoke the old one.
Revoke. Instant. The next request with that key will return 401 unauthorized.

Scopes

A scope gates a route. v1 grants every key the full set below. Keys are admin-minted from Settings → Developers and inherit the organization's own authority. A future scope picker will let you narrow this per key.

Scope	Allows
`workspaces:read`	Read the workspace this key belongs to.
`channels:read`	List connected channels and their stats/health.
`media:read`	List and read media in the library.
`posts:read`	List and read posts, drafts, and scheduled posts.
`posts:write`	Create, schedule, publish, and delete posts and media.
`analytics:read`	Read post and channel analytics.

Read which scopes a key holds at runtime via GET /me (key.scopes). The new read scopes (workspaces:read, media:read, and analytics:read) were added with the read surface. Existing keys were granted them automatically, so nothing you've already issued needs reminting.

What we log per request

Every authenticated request writes an audit row to api_request_log with:

API key id (never the secret)
HTTP method & path
Response status code
Caller IP (first hop of X-Forwarded-For) and User-Agent
Idempotency-Key (when present)
Server-side request duration in milliseconds
Truncated error message when the response was a 4xx/5xx