POSTARD DEVELOPERS

Authentication and API keys

Use a workspace API key for a server integration. Use a Postard app session for dashboard actions, or OAuth with explicit workspace consent for MCP.

Create and protect a key

A workspace owner or admin can open Developer access and create a read-only key, or allow it to save text drafts. An active paid plan or trial with an unexpired entitlement is required. Billing activation is still pending; publishing this code does not create a paid subscription.

The secret starts with psk_, is shown once, and is stored only as a SHA-256 digest. Keep it in server-side environment variables. Never put a key in browser code, a public repository or an AI conversation. Revoke a leaked key immediately.

Supported key endpoints

Keys can list their own workspace, read recent drafts, save a draft, list connected profiles and read saved metric snapshots. Media, scheduling, OAuth, email, analytics, billing and key management still require first-party app sessions. A key cannot publish content.

curl "$POSTARD_API_URL/v1/workspaces/$WORKSPACE_ID/drafts" \
  --header "Authorization: Bearer $POSTARD_API_KEY"

For GET /v1/workspaces, also send X-Postard-Workspace: <workspace UUID>. Only that key’s workspace is returned.

Safe draft retries

Creating a draft with an API key requires an Idempotency-Key UUID. Generate it once for a logical save and reuse it when retrying identical input. A successful retry returns the original draft, sets Idempotency-Replayed: true, and does not consume another call. Reusing it for different content returns 409. Key revocation and current access are still checked on retries.

curl --request POST \
  "$POSTARD_API_URL/v1/workspaces/$WORKSPACE_ID/drafts" \
  --header "Authorization: Bearer $POSTARD_API_KEY" \
  --header "Idempotency-Key: $REQUEST_UUID" \
  --header "Content-Type: application/json" \
  --data '{"title":"A fresh perspective","content":"One useful idea."}'

Revocation, roles and plan changes

Every call checks the key’s workspace, scopes, owner’s current admin role, plan and expiry. Solo allows one active key, Creator five, Agency unlimited. After a downgrade, the oldest permitted keys remain usable and extra keys are disabled. Revoked keys never become active again.

App sessions and MCP

First-party Supabase app sessions are verified for issuer, signature, expiry and audience. A publishable Supabase key is not user authentication. Service-role keys belong only in trusted backend configuration. MCP accepts registered, audience-bound OAuth clients with PKCE and selected-workspace consent; an API key is not an MCP login. OAuth consent never elevates a user’s workspace role.