Social Networks

A social network is your BYOK(bring-your-own-key) OAuth application for a given platform. Before you can connect an end-user account, you register the platform’s OAuth app credentials here — the client_id and client_secret issued to you by X, LinkedIn, Meta, Google, and so on. The client secret is encrypted at rest and is never returned by any endpoint.

Records are keyed by (org, platform): creating a network for a platform you already configured upserts the existing row rather than creating a duplicate. Supported platform values are x, linkedin, instagram, tiktok, youtube, facebook, threads, bluesky, pinterest, google_business, and reddit.

Configuring a network is optional for platforms PostFuze ships a shared one-click app for: you can start the hosted OAuth flow withPOST /social-networks/{platform}/auth-url and finish connecting accounts via the Social Accounts connect endpoints even without a BYOK app. Register your own app here when you want a white-label consent screen or a platform that has no shared app.

The social network object

Field	Type	Description
`id`	string	Unique identifier for the network record.
`platform`	enum	The platform this OAuth app targets.
`display_name`	string \| null	Optional human-friendly label for the app.
`client_id`	string \| null	The OAuth app’s public client identifier.
`redirect_uri`	string \| null	Default redirect URI registered with the provider.
`scopes`	string[]	OAuth scopes requested during the connect flow.
`extra_config`	object	Arbitrary platform-specific configuration.
`is_enabled`	boolean	Whether this network can be used to connect accounts.
`created_at` / `updated_at`	timestamp	Creation and last-update timestamps.

The client_secret is write-only. It is accepted on create/update and stored encrypted, but is never present in any response body.

Create or update a network

POST /social-networks

Registers OAuth app credentials for a platform. If a network already exists for the same (org, platform) pair, its fields are updated in place. Omitting client_secret on an upsert preserves the previously stored secret.

Parameter	Type	Required	Description
`platform`	enum	Yes	One of the eleven supported platform identifiers.
`client_id`	string	No	The OAuth app’s client identifier.
`client_secret`	string	No	The OAuth app’s client secret. Stored encrypted; never returned.
`display_name`	string	No	Optional label for the app.
`redirect_uri`	string (URL)	No	Default redirect URI registered with the provider.
`scopes`	string[]	No	OAuth scopes to request.
`extra_config`	object	No	Platform-specific configuration.
`is_enabled`	boolean	No	Whether the network is usable. Defaults to enabled.

curl

curl https://api.postfuze.com/api/v1/social-networks \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "x",
    "display_name": "Acme X App",
    "client_id": "VGhpc0lzQUNsaWVudElk",
    "client_secret": "super-secret-value",
    "redirect_uri": "https://app.acme.com/oauth/callback",
    "scopes": ["tweet.read", "tweet.write", "users.read", "offline.access"]
  }'

201 Created

{
  "id": "f3c1b0a2-8d4e-4a9f-9b1c-2e7d6f0a1234",
  "platform": "x",
  "display_name": "Acme X App",
  "client_id": "VGhpc0lzQUNsaWVudElk",
  "redirect_uri": "https://app.acme.com/oauth/callback",
  "scopes": ["tweet.read", "tweet.write", "users.read", "offline.access"],
  "extra_config": {},
  "is_enabled": true,
  "created_at": "2026-06-09T12:00:00.000Z",
  "updated_at": "2026-06-09T12:00:00.000Z"
}

List networks

GET /social-networks

Returns every configured network for your organization, ordered by platform. Deleted networks are excluded.

curl

curl https://api.postfuze.com/api/v1/social-networks \
  -H "Authorization: Bearer sk_live_…"

200 OK

{
  "data": [
    {
      "id": "f3c1b0a2-8d4e-4a9f-9b1c-2e7d6f0a1234",
      "platform": "x",
      "display_name": "Acme X App",
      "client_id": "VGhpc0lzQUNsaWVudElk",
      "redirect_uri": "https://app.acme.com/oauth/callback",
      "scopes": ["tweet.read", "tweet.write", "users.read", "offline.access"],
      "extra_config": {},
      "is_enabled": true,
      "created_at": "2026-06-09T12:00:00.000Z",
      "updated_at": "2026-06-09T12:00:00.000Z"
    }
  ]
}

Retrieve a network

GET /social-networks/{id}

Fetches a single network by its id. Returns 404 if the network does not exist or has been deleted.

curl

curl https://api.postfuze.com/api/v1/social-networks/f3c1b0a2-8d4e-4a9f-9b1c-2e7d6f0a1234 \
  -H "Authorization: Bearer sk_live_…"

200 OK

{
  "id": "f3c1b0a2-8d4e-4a9f-9b1c-2e7d6f0a1234",
  "platform": "x",
  "display_name": "Acme X App",
  "client_id": "VGhpc0lzQUNsaWVudElk",
  "redirect_uri": "https://app.acme.com/oauth/callback",
  "scopes": ["tweet.read", "tweet.write", "users.read", "offline.access"],
  "extra_config": {},
  "is_enabled": true,
  "created_at": "2026-06-09T12:00:00.000Z",
  "updated_at": "2026-06-09T12:00:00.000Z"
}

Update a network

PATCH /social-networks/{id}

Updates one or more fields on an existing network. Every field is optional; only the fields you send are changed. Sending a new client_secret rotates the stored secret, while omitting it leaves the existing secret intact.

Parameter	Type	Required	Description
`client_id`	string	No	Replace the OAuth client identifier.
`client_secret`	string	No	Rotate the encrypted client secret.
`display_name`	string	No	Replace the label.
`redirect_uri`	string (URL)	No	Replace the redirect URI.
`scopes`	string[]	No	Replace the requested scopes.
`extra_config`	object	No	Replace platform-specific configuration.
`is_enabled`	boolean	No	Enable or disable the network.

curl

curl -X PATCH https://api.postfuze.com/api/v1/social-networks/f3c1b0a2-8d4e-4a9f-9b1c-2e7d6f0a1234 \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "client_secret": "rotated-secret-value",
    "is_enabled": true
  }'

200 OK

{
  "id": "f3c1b0a2-8d4e-4a9f-9b1c-2e7d6f0a1234",
  "platform": "x",
  "display_name": "Acme X App",
  "client_id": "VGhpc0lzQUNsaWVudElk",
  "redirect_uri": "https://app.acme.com/oauth/callback",
  "scopes": ["tweet.read", "tweet.write", "users.read", "offline.access"],
  "extra_config": {},
  "is_enabled": true,
  "created_at": "2026-06-09T12:00:00.000Z",
  "updated_at": "2026-06-09T12:05:30.000Z"
}

Delete a network

DELETE /social-networks/{id}

Soft-deletes the network and disables it. Already-connected accounts are unaffected, but no new accounts can be connected through this app until it is reconfigured.

curl

curl -X DELETE https://api.postfuze.com/api/v1/social-networks/f3c1b0a2-8d4e-4a9f-9b1c-2e7d6f0a1234 \
  -H "Authorization: Bearer sk_live_…"

200 OK

{
  "id": "f3c1b0a2-8d4e-4a9f-9b1c-2e7d6f0a1234",
  "deleted": true
}

Start the OAuth flow

POST /social-networks/{platform}/auth-url

Builds the platform’s authorization URL with a signed state parameter so you can redirect the end user into the hosted OAuth flow. It uses your configured BYOKapp for the platform when one is enabled; otherwise it falls back to PostFuze’s shared one-click app, so the call succeeds even when you have not registered your own app. It only returns 400 for the rare platform that has neither a BYOK app nor a shared app available. The path parameter is the platform identifier (e.g. facebook), not the network id.

Parameter	Type	Required	Description
`redirect_uri`	string	No	Where to send the user after the connect flow completes. Encoded into the signed state.
`tenant_id`	string	No	Associates the resulting account with one of your end tenants.
`scopes`	string[]	No	Override the network’s default scopes for this authorization.

curl

curl https://api.postfuze.com/api/v1/social-networks/facebook/auth-url \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_uri": "https://app.acme.com/connected",
    "tenant_id": "tenant_42"
  }'

200 OK

{
  "auth_url": "https://www.facebook.com/v19.0/dialog/oauth?client_id=…&redirect_uri=…&state=…&scope=pages_manage_posts%2Cpages_read_engagement"
}

Redirect the user to auth_url. After they approve, the provider returns to our callback, which mints a session token and hands off to the page-selection and finalize endpoints.