Skip to content

Bring Your Own Key OAuth API: Connect Social Accounts Through Your Own OAuth App

A bring your own key OAuth API lets a product connect social accounts through its own OAuth app while a separate service handles the callback, token exchange, encrypted storage, token refresh, posting, and scheduling. You supply the platform credentials; the service runs the connection and publishing infrastructure behind them.

What bring your own key means for OAuth connections

With bring your own key, authorization occurs under an OAuth app that you control, instead of under a managed app provided by the posting service. The person connecting an account still goes through a familiar flow, yet the consent screen displays your app name and branding. That difference becomes important when the connection is embedded in a SaaS product, white-label product, agency platform, creator tool, or internal publishing system, because customers and security teams may need to know precisely which app they are authorizing.

Managed apps vs your own app: decision criteria

Managed OAuth apps offer the quickest route when speed is the priority: there is no developer console setup, no app review work, and no platform-specific OAuth maintenance to handle. Bring your own key introduces setup and ongoing maintenance in return for ownership. Use managed apps to prototype quickly. Use your own OAuth app when users should see your app name during authorization, the consent screen should reflect your product, platform quotas and app review history should be yours, security and compliance teams should be able to audit the exact OAuth app in use, or integrations need a straightforward explanation of which app is being authorized. The service continues to manage the callback URL, token exchange, encrypted token storage, token refresh, posting, scheduling, and analytics. You provide the platform credentials, and the service operates the underlying pipes.

Setup field map and callback URL pattern

Setup involves four steps. First, create an OAuth app in the platform developer console. Second, configure the platform callback URL to point to the service callback for that platform. Third, register that app with the service. Fourth, include the returned app identifier when connecting an account. Each OAuth platform uses the callback URL pattern shown in the Callback URL pattern and examples example. Create the app in the platform developer portal, paste the matching callback URL there, then copy the app clientId and clientSecret into the registration request. In the dashboard, open your project, go to the apps area, and choose the option for adding an OAuth app. Select the relevant platform, enter a display name, enter the clientId and clientSecret values, and save. Through the API, use the Register an OAuth app example. The response includes the created app, as shown in the App registration response example. Save the returned app id and pass it as appId when you start the account connection flow. The clientSecret is stored encrypted and is never returned by the API, so treat the registration response as confirmation of the clientId and app id, not as a place to recover the secret later.

Worked example: register app, connect account, post

Once the app is registered, start the normal connect flow and add appId, as shown in the Connect an account with appId example. The service returns an authorization URL, as shown in the Authorization URL response example. Send your user to that URL. After the user authorizes the account, the platform sends them back to the service callback. The service then completes the token exchange, persists the tokens, and adds an integration to your project. If you want the user to return to a page in your product once connection completes, pass redirectUri too, as shown in the Connect with redirectUri example. When profiles are used to link connected accounts with users in your product, include profileId in the same request, as shown in the Connect with profileId and redirectUri example. After OAuth completes, list integrations for that profile, as shown in the List integrations for a profile example, and use the returned integration id as accountId when posting. Check each step before moving on: confirm the app id matches the platform you intended, confirm the redirectUri is the page your product expects after connection, confirm the profileId belongs to the user who is connecting, and confirm the integration returned for that profile is the one you pass as accountId.

Posting, scheduling, and analytics stay the same

Once the account is connected, posting does not change. You still create posts through the same endpoint, as shown in the Create a post after connection example. Scheduling, analytics, and media upload also continue to behave as before. The only difference is at the connection layer: the user authorized your app, and the service runs the infrastructure behind it. That separation makes migration practical. Start with managed OAuth apps while you prototype, then create your own platform apps, register them, and start connecting new accounts with appId when the product needs tighter control, without rebuilding posting, scheduling, or token refresh across platforms.

Rotating secrets and migration rules

You can update an app name, image, or clientSecret, as shown in the Rotate clientSecret example. The platform and clientId cannot be changed after creation. That rule is intentional: refresh tokens are tied to the clientId that issued them, and changing it would break existing integrations. When a different platform app is required, register a new app and reconnect the account under the new appId. Before rotating, confirm you are updating the secret for the same clientId, then verify that existing integrations still work after the change. If the clientId itself must change, plan a reconnection rather than an in-place edit.

Contract sheet: exact endpoints, parameters, and responses

Bring your own key fits a social media scheduler whose users connect accounts through your brand, an AI agent that posts for customers under your product app, and an enterprise workflow where the security team owns the platform app while the service handles posting infrastructure. Managed apps suit teams prioritizing speed. Own keys suit teams prioritizing ownership. The contract sheet below preserves the exact methods, paths, parameters, and response fields for registration, connection, integration listing, posting, and secret rotation, so you can implement against the same field names from the first request.

Managed OAuth apps vs bring your own key
Decision factorManaged OAuth appsBring your own key
Setup effortLowest; no developer console setupHigher; create and register your own OAuth app
Consent screenShows the managed appShows your app name and brand
Quota and review historyBelongs to the managed appBelongs to your platform app
AuditabilityLess direct for your security teamYour team can audit the exact OAuth app
MaintenanceManaged for youYou own platform app maintenance
Best fitPrototyping and speedBranded products, enterprise, and ownership

Based on trade-offs stated in the source; platform-specific review and quota rules are not supplied.

Field map for registration, connection, and posting
FieldWhere it appearsPurpose
platformPOST /v1/apps/ request; POST /v1/posts platforms[]Identifies the social platform
namePOST /v1/apps/ request; app responseHuman-readable name for your OAuth app
clientIdPOST /v1/apps/ request; app responsePlatform app client identifier; immutable after creation
clientSecretPOST /v1/apps/ request; PATCH /v1/apps/app_123 requestPlatform app secret; stored encrypted and never returned
appIdGET /v1/connect/twitter query parameterRegistered app id used to connect an account under your app
redirectUriGET /v1/connect/twitter query parameterOptional page in your product to return to after connection
profileIdGET /v1/connect/twitter and GET /v1/connect/integrations query parametersMaps the connected account to a user in your product
accountIdPOST /v1/posts platforms[]Integration id returned when listing integrations; identifies the connected account to post to

Exact source field names preserved.

Failure and rotation matrix
ChangeAllowed after creationConsequence
nameYesUpdate without changing the issuing client
imageYesUpdate app presentation
clientSecretYes, via PATCH /v1/apps/app_123Rotate the secret for the same clientId
platformNoCreate a new app and reconnect
clientIdNoRefresh tokens are tied to the issuing clientId; changing it would break existing integrations

Exact source rules preserved; do not reinterpret.

Exact endpoint contract sheet
Method and pathParameters and fieldsResponse or effect
POST {{API_BASE_URL}}/v1/apps/Request: platform, name, clientId, clientSecretResponse: success, app{id, platform, name, imageUrl, clientId, integrationCount, createdAt, updatedAt}; clientSecret never returned
GET {{API_BASE_URL}}/v1/connect/twitterQuery: appId required for this flow; optional redirectUri, profileIdResponse: url authorization URL; platform callback exchanges code, stores tokens, creates integration
GET {{API_BASE_URL}}/v1/connect/integrationsQuery: profileIdReturns integrations for the profile; use returned integration id as accountId
POST {{API_BASE_URL}}/v1/postsRequest: platforms[{platform, accountId}], contentCreates a post for the connected account
PATCH {{API_BASE_URL}}/v1/apps/app_123Request: clientSecretUpdates the secret; platform and clientId cannot change
Callback pattern {{API_BASE_URL}}/v1/connect/{platform}/callbackSet as the callback URL in the platform developer consoleExamples: /v1/connect/twitter/callback, /v1/connect/linkedin/callback, /v1/connect/youtube/callback

Origin modularized as {{API_BASE_URL}}; methods, paths, field names, and trailing slash preserved exactly from the source contract.

Register an OAuth app
curl -X POST {{API_BASE_URL}}/v1/apps/ \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "twitter",
    "name": "Acme Twitter OAuth App",
    "clientId": "YOUR_PLATFORM_CLIENT_ID",
    "clientSecret": "YOUR_PLATFORM_CLIENT_SECRET"
  }'
App registration response
{
	"success": true,
	"app": {
		"id": "app_123",
		"platform": "twitter",
		"name": "Acme Twitter OAuth App",
		"imageUrl": null,
		"clientId": "YOUR_PLATFORM_CLIENT_ID",
		"integrationCount": 0,
		"createdAt": "2026-05-25T10:00:00.000Z",
		"updatedAt": "2026-05-25T10:00:00.000Z"
	}
}
Connect an account with appId
curl "{{API_BASE_URL}}/v1/connect/twitter?appId=app_123" \
  -H "x-access-key: YOUR_API_KEY"
Authorization URL response
{
	"url": "https://twitter.com/i/oauth2/authorize?response_type=code&client_id=..."
}
Connect with redirectUri
curl "{{API_BASE_URL}}/v1/connect/twitter?appId=app_123&redirectUri=https://yourapp.com/settings/integrations" \
  -H "x-access-key: YOUR_API_KEY"
Connect with profileId and redirectUri
curl "{{API_BASE_URL}}/v1/connect/twitter?appId=app_123&profileId=profile_456&redirectUri=https://yourapp.com/settings/integrations" \
  -H "x-access-key: YOUR_API_KEY"
List integrations for a profile
curl "{{API_BASE_URL}}/v1/connect/integrations?profileId=profile_456" \
  -H "x-access-key: YOUR_API_KEY"
Create a post after connection
curl -X POST {{API_BASE_URL}}/v1/posts \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platforms": [
      {
        "platform": "twitter",
        "accountId": "integration_789"
      }
    ],
    "content": "A short example update."
  }'
Rotate clientSecret
curl -X PATCH {{API_BASE_URL}}/v1/apps/app_123 \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientSecret": "NEW_PLATFORM_CLIENT_SECRET"
  }'