Core resource

Profiles & connections

Create hosted connection URLs, list the resulting social identities, and monitor token health.

Endpoint summary

All operations in this resource, with the minimum accepted key scope.

Method & endpointPurposeScope

GET/api/profiles

List connected profiles

read

POST/api/profiles/connect

Create a hosted connection URL

full

GET/api/profiles/{id}

Get a connected profile

read

GET/api/profiles/{id}/health

Inspect connection and token health

read

GET/api/profiles/{id}/boards

List Pinterest boards for a board picker

read

GET/api/profiles/{id}/stats

Read profile analytics snapshots

read

DELETE/api/profiles/{id}

Disconnect and delete credentials

full

GET/api/connect-origins

List origins allowed as return_url

read

POST/api/connect-origins

Allow an origin to receive the redirect

full

Register your product’s origin first

PostGate only redirects a finished connection back to an origin you registered. Do this once per product, from your backend or under Dashboard → API keys → Connect origins. HTTPS is required outside loopback, and a workspace may register up to 25 origins.

Allow an originPostGate API

curl -X POST https://postgate.studio/api/connect-origins \
  -H "Authorization: Bearer $POSTGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "origin": "https://app.example.com", "label": "Production SaaS" }'

Start a hosted connection

Create a short-lived URL on your backend, then redirect the customer’s browser to it. The URL expires after 15 minutes. To your customer the whole flow looks native: they leave your product, authorize the network, and come straight back.

Create connection URLPostGate API

curl -X POST https://postgate.studio/api/profiles/connect \
  -H "Authorization: Bearer $POSTGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "instagram",
    "profile_group_id": "grp_acme123",
    "return_url": "https://app.example.com/settings/social"
  }'

LinkedIn organization Pages

Send linkedin_account_type: "organization" to POST /api/profiles/connect. The owner authorizes the Community Management app and selects the Pages to connect. Personal profiles use member by default. Check GET /api/integrations/linkedin or MCP get_linkedin_connection_options for local availability; Page connections return 503 until enabled. Page analytics, comments, messages and import are disabled. The MCP connect_profile tool accepts the same field.

LinkedIn PagesPostGate API

{
  "platform": "linkedin",
  "profile_group_id": "grp_acme123",
  "linkedin_account_type": "organization",
  "return_url": "https://app.example.com/settings/social"
}

Redirect, then read what came back

Open the returned url. When the network finishes, PostGate returns the browser to your return_url with connected (how many accounts were attached) and connection_platform. If the customer cancels or the provider refuses, it returns connection_error and connection_platform instead. Credential-based providers append profile_id. List profiles by group to read the full result.

Response, then the redirectPostGate API

{
  "platform": "instagram",
  "url": "https://postgate.studio/connect/eyJ...",
  "expires_in": 900
}

# success
https://app.example.com/settings/social?connected=1&connection_platform=instagram

# canceled or refused
https://app.example.com/settings/social?connection_error=...&connection_platform=instagram

Credential-based connections

Most platforms use OAuth. Bluesky uses an app password, Telegram uses a bot token and destination chat, and Mastodon also requires instance_url when the connection URL is created. The hosted page collects secrets directly; your product does not need to proxy them.

Let customers pick a Pinterest board

Pinterest requires options.pinterest.board_id on every Pin. Read the connected account’s boards live and render a picker instead of asking for an ID. PostGate does not store boards and never exposes the access token — the call is proxied server side. Non-Pinterest profiles return platform_not_configured; a connection authorized in Sandbox, or authorized before boards:read was requested, must be reconnected first.

List boardsPostGate API

curl https://postgate.studio/api/profiles/pro_pinterest123/boards \
  -H "Authorization: Bearer $POSTGATE_API_KEY"

{
  "data": [
    { "id": "1099...", "name": "Launches", "description": "Product news", "privacy": "PUBLIC" }
  ],
  "meta": { "profile_id": "pro_pinterest123", "fetched_at": "2025-01-14T10:00:00.000Z" }
}

Monitor health before publishing

Use the health endpoint to surface status, granted scopes, token expiry, and reconnect_required. A reconnect keeps the durable profile identity where the provider flow allows it.

Profile healthPostGate API

curl https://postgate.studio/api/profiles/pro_instagram123/health \
  -H "Authorization: Bearer $POSTGATE_API_KEY"

Endpoint summary

Register your product’s origin first

Start a hosted connection

LinkedIn organization Pages

Redirect, then read what came back

Credential-based connections

Let customers pick a Pinterest board

Monitor health before publishing

Continue building