Accounts

GET /api/v1/accounts returns the list of platform providers the authenticated user has connected. It's the "is this account connected?" answer — useful before you call /publish so you don't fire a request at a platform the user hasn't authorized.

This endpoint will never return secrets, tokens, refresh tokens, or webhook URLs. If a downstream tool needs the actual credential, that path does not go through the public API.

Required scope: accounts.read. Rate limit: 600 requests per minute per key.

Request

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

Response

{
  "ok": true,
  "accounts": [
    {
      "provider": "beehiiv",
      "kind": "byok",
      "connected_at": "2026-04-01T12:00:00.000Z",
      "last_used_at": "2026-05-21T18:00:00.000Z",
      "expires_at": null
    },
    {
      "provider": "instagram",
      "kind": "oauth",
      "connected_at": "2026-03-15T10:24:00.000Z",
      "last_used_at": "2026-05-22T08:00:00.000Z",
      "expires_at": "2026-08-01T10:24:00.000Z"
    }
  ]
}

Field guide

• provider (string) — the platform identifier, same vocabulary as the platforms array in /publish.
• kind (string) — "byok" if the user supplied credentials directly (Beehiiv, Ghost, Bluesky app-password, Mastodon, Discord webhook). "oauth" if the user went through an OAuth2 flow (Instagram, Threads, TikTok, YouTube, LinkedIn, Pinterest, Patreon, Twitch).
• connected_at (ISO 8601) — when the credential was first stored.
• last_used_at (ISO 8601 or null) — best-effort "this credential was touched recently". Useful for spotting dormant connections.
• expires_at (ISO 8601 or null) — for OAuth providers that issue short-lived tokens. null for BYOK and for OAuth providers that never expire (e.g. long-lived Facebook page tokens). When this is in the past, Post-EZ will attempt a refresh on the next dispatch.

Ordering

Rows are returned sorted by kind, then by provider alphabetically. This is stable across calls so you can diff the array client-side to detect newly connected or removed accounts without false positives from row ordering.

Errors

The usual 401 (missing / invalid key), 403 (wrong scope), and 429 (rate limited). A 500 { ok: false, error: "query_failed" } indicates a transient database issue — retry with backoff.