OAuth Flows

SocialAPI uses OAuth in two distinct contexts:

Connecting platform accounts (Instagram, Facebook, etc.) to your SocialAPI account so you can manage them through the API.
Authenticating MCP/API clients (Claude, ChatGPT, Cursor) via the built-in OAuth 2.1 authorization server so they can call the API on your behalf.

Connecting platform accounts

SocialAPI manages platform OAuth on your behalf. Your application kicks off the connection, sends the user to the platform’s consent screen, and receives a redirect back to a URL of your choice with the result. You never see or store platform access tokens — SocialAPI persists them encrypted and proxies all subsequent calls. This is a managed connection pattern, not an OAuth flow you implement against SocialAPI. For OAuth 2.1 (used by MCP and third-party API clients calling SocialAPI), see the section below.

Step 1: Initiate the connection

Call POST /v1/accounts/connect with the platform slug, your post-connection redirect_uri, and an optional state value for correlation:

curl -X POST https://api.social-api.ai/v1/accounts/connect \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "instagram",
    "redirect_uri": "https://app.example.com/oauth/callback",
    "state": "session_abc123"
  }'

Fields:

Field	Location	Required	Notes
`platform`	top-level	yes	Platform slug (`instagram`, `facebook`, `threads`, `tiktok`, `linkedin`, `twitter`, `youtube`, `google`).
`redirect_uri`	top-level	recommended	Your post-connection callback. If you have registered any redirect URIs, this must match one of them (see Whitelisting redirect URIs). If omitted, the user sees a built-in HTML success page instead of being redirected.
`state`	top-level	optional	Opaque correlation value, max 512 chars, echoed back verbatim in the final redirect. Use it to tie the result to a session on your side.
`brand_id`	top-level	optional	Attach the account to an existing brand. If omitted, a new brand is auto-created.
`metadata`	top-level	optional	Platform-specific connection data only (for example, TikTok BYOK uses this for `apikey`). For standard managed OAuth this is empty or omitted.

Response (HTTP 202):

{
  "auth_url": "https://www.instagram.com/oauth/authorize?client_id=...&state=...",
  "state": "4a8f2c1e9b3d7f06a5c2e8b4d1f3a7e2",
  "message": "Redirect the user to auth_url"
}

The state in the response is SocialAPI’s internal CSRF token used between our connect call and our platform callback. Your application does not need to read or store it; just send the user to auth_url.

Step 2: User authorizes on the platform

Redirect your user to the auth_url. They log in to the platform and grant permissions. The platform redirects back to SocialAPI’s callback (not yours). SocialAPI exchanges the code for an access token, persists it encrypted, and then 302-redirects the user to your redirect_uri.

Step 3: Receive the result at your `redirect_uri`

Success:

https://app.example.com/oauth/callback
  ?status=success
  &platform=instagram
  &state=session_abc123
  &account_id=acc_01HZ9X3Q4R5M6N7P8V2K0W1J

One connection produces exactly one account_id. Facebook accounts that manage multiple Pages still resolve to a single account in the connection result; Page details are exposed separately under /v1/accounts/{id}/pages and are not part of this flow. Error (the user denied consent, the platform returned an error, or the link expired):

https://app.example.com/oauth/callback
  ?status=error
  &error=access_denied
  &error_description=The+user+denied+the+request
  &platform=instagram
  &state=session_abc123

Always check status first. On success, persist the account_id against your user record and call /v1/accounts/{id} for full account details. On error, surface a retry path in your UI — the customer can restart from Step 1. This only applies to Google logins that manage more than one Business Profile. A Google login with a single Profile connects like any other platform, in a single request, with no extra step. Google accounts can manage several Business Profiles under one login (for example, a chain with multiple locations). When that happens, SocialAPI cannot know which Profile you want to connect, so it does not create an account yet. Instead it stores a pending connection and asks you to choose. Server-callback flow. If the Google login you just authorized manages more than one Profile, your redirect_uri receives status=selection_required instead of status=success, along with a connection_id:

https://app.example.com/oauth/callback
  ?status=selection_required
  &connection_id=pc_4a8f2c1e9b3d7f06a5c2e8b4d1f3a7e2
  &state=session_abc123

Proxy flow. If your server exchanges the authorization code itself via POST /v1/oauth/exchange, the same fork happens in the response body. A single Profile still returns the usual ConnectAccountResponse (HTTP 201). More than one Profile returns HTTP 200 instead:

{
  "status": "selection_required",
  "connection_id": "pc_4a8f2c1e9b3d7f06a5c2e8b4d1f3a7e2",
  "platform": "google",
  "profiles": [
    {
      "platform_account_id": "accounts/123/locations/456",
      "display_name": "Joe's Pizza (Downtown)",
      "username": "",
      "profile_picture_url": "",
      "bio": "Wood-fired pizza since 1998"
    },
    {
      "platform_account_id": "accounts/123/locations/789",
      "display_name": "Joe's Pizza (Uptown)",
      "username": "",
      "profile_picture_url": "",
      "bio": ""
    }
  ]
}

Resolving the selection. In both cases no account exists yet. Finish the connection with the connection_id:

GET /v1/accounts/pending/{connection_id} lists the candidate Profiles. This is usually optional since the callback redirect or the exchange response already includes them, but it is useful to re-fetch the list or check whether the pending connection is still valid.

curl https://api.social-api.ai/v1/accounts/pending/pc_4a8f2c1e9b3d7f06a5c2e8b4d1f3a7e2 \
  -H "Authorization: Bearer $SOCAPI_KEY"

POST /v1/accounts/pending/{connection_id}/select with the platform_account_id of exactly one Profile connects it:

curl -X POST https://api.social-api.ai/v1/accounts/pending/pc_4a8f2c1e9b3d7f06a5c2e8b4d1f3a7e2/select \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform_account_id": "accounts/123/locations/456"}'

This returns the same ConnectAccountResponse (HTTP 201) as a normal single-Profile connect.

A pending connection is single-use and expires 30 minutes after it is created. The first successful selection consumes it: a second select call, or one made after expiry, returns 404. Selecting a platform_account_id that is not in the returned candidate set returns 400.

Fallback when `redirect_uri` is omitted

If your connect call did not include redirect_uri, SocialAPI renders a built-in HTML success or error page in place of the redirect. This is intended for ad-hoc connections (for example, the SocialAPI dashboard itself); production integrations should always supply redirect_uri.

Whitelisting redirect URIs

Redirect URI enforcement is optional until you register your first URI. If your workspace has no redirect URIs registered, any valid redirect_uri (https, or http for localhost) is accepted when starting a connect flow. As soon as you register one or more URIs, every redirect_uri must match an entry in your list, and unmatched values are rejected with a 400 error. Deleting all registered URIs returns your workspace to open mode. Register URIs from the SocialAPI dashboard under Settings → OAuth redirect URIs. The management API exists at /v1/oauth/redirect-uris but is dashboard-only (requires the dashboard JWT, not an API key). We recommend registering your production redirect URIs to lock down where users can be sent after OAuth.

Correlation `state` (customer-controlled)

The top-level state field on POST /v1/accounts/connect is your correlation token, not a security primitive enforced by SocialAPI. It is echoed back unchanged in the final redirect. Common uses:

Tie the redirect to the originating session (set state to a server-side session ID).
CSRF defense for your own application — generate a random value, store it in the user’s session, and verify it matches when the redirect lands.

SocialAPI does not validate state. If you do not pass one, the final redirect will include state= with an empty value.

Listing connected accounts

curl https://api.social-api.ai/v1/accounts \
  -H "Authorization: Bearer $SOCAPI_KEY"

Reconnecting an account

If you call POST /v1/accounts/connect for an account that is already connected, the flow runs again and the stored token is upserted. This is safe to call when tokens expire and is the supported path for token refresh on platforms that lack long-lived tokens.

Disconnecting an account

DELETE /v1/accounts/{id} removes the account and the tokens we hold for it. Where the platform offers a token-revocation endpoint, we also revoke the grant on the platform during disconnect: Facebook, Google, Instagram, Threads, X, TikTok, and YouTube all support this. LinkedIn, Pinterest, and Zalo do not offer a revocation API, so disconnect removes only the token stored on our side. On those platforms the user still sees the app authorized in their account settings and must remove it manually. If you offboard users under GDPR or similar rules, account for this manual step on those three platforms. This is separate from POST /oauth/revoke below, which revokes SocialAPI’s own OAuth 2.1 tokens issued to MCP clients, not a platform grant.

OAuth 2.1 for MCP and API clients

SocialAPI includes a built-in OAuth 2.1 authorization server that enables MCP clients (Claude, ChatGPT, Cursor) and other third-party applications to authenticate users and call the API on their behalf. The implementation follows these RFCs:

RFC 8414 for authorization server metadata discovery
RFC 7591 for dynamic client registration
RFC 7636 for PKCE (required)
RFC 7009 for token revocation

Discovery

Clients can discover the authorization server configuration at:

GET /.well-known/oauth-authorization-server

Response:

{
  "issuer": "https://api.social-api.ai",
  "authorization_endpoint": "https://api.social-api.ai/oauth/authorize",
  "token_endpoint": "https://api.social-api.ai/oauth/token",
  "registration_endpoint": "https://api.social-api.ai/oauth/register",
  "revocation_endpoint": "https://api.social-api.ai/oauth/revoke",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_methods_supported": ["client_secret_post"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["social:all"]
}

Step 1: Register a client

curl -X POST https://api.social-api.ai/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My MCP Client",
    "redirect_uris": ["https://app.example.com/callback"]
  }'

Response (HTTP 201):

{
  "client_id": "a1b2c3d4e5f6...",
  "client_secret": "s3cr3t...",
  "client_id_issued_at": 1719000000,
  "client_secret_expires_at": 0,
  "client_name": "My MCP Client",
  "redirect_uris": ["https://app.example.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "client_secret_post"
}

The client_secret is returned once. Store it securely. It cannot be retrieved again.

Step 2: Authorize the user

Redirect the user to the authorization endpoint with PKCE parameters:

GET /oauth/authorize
  ?client_id=a1b2c3d4e5f6...
  &redirect_uri=https://app.example.com/callback
  &response_type=code
  &scope=social:all
  &state=random_csrf_value
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

The API validates the client and redirect URI, then redirects the user to the SocialAPI dashboard consent screen. After the user approves, they are redirected back to your redirect_uri with ?code=...&state=....

PKCE is required. The only supported challenge method is S256. Requests without a code_challenge are rejected with 400.

Single scope. The only supported scope is social:all, which grants full access to the user’s account. This is the default if no scope is specified.

Step 3: Exchange the code for tokens

curl -X POST https://api.social-api.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE_HERE" \
  -d "client_id=a1b2c3d4e5f6..." \
  -d "client_secret=s3cr3t..." \
  -d "code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk" \
  -d "redirect_uri=https://app.example.com/callback"

Response:

{
  "access_token": "eyJhbGciOiJFZERTQSIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_a1b2c3d4...",
  "scope": "social:all"
}

The access token is an EdDSA/Ed25519 signed JWT valid for 1 hour. Use it as a Bearer token for all /v1 endpoints.

Per RFC 6749 section 2.3.1, the token endpoint also accepts client credentials via HTTP Basic authentication. Send Authorization: Basic base64(client_id:client_secret) instead of including client_id and client_secret in the request body. Body parameters take precedence if both are present.

Step 4: Refresh the access token

When the access token expires, use the refresh token to get a new pair:

curl -X POST https://api.social-api.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=rt_a1b2c3d4..." \
  -d "client_id=a1b2c3d4e5f6..."

The response contains a new access token and a new refresh token. The old refresh token is invalidated (rotation is enforced). Refresh tokens expire after 30 days.

Revoking tokens

To revoke a refresh token (for example, on user logout):

curl -X POST https://api.social-api.ai/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=rt_a1b2c3d4..." \
  -d "client_id=a1b2c3d4e5f6..."

Per RFC 7009, this endpoint always returns 200, even if the token is already invalid.

Supporting endpoints

Endpoint	Method	Purpose
`/.well-known/oauth-authorization-server`	GET	RFC 8414 metadata discovery
`/oauth/register`	POST	RFC 7591 dynamic client registration
`/oauth/authorize`	GET	Authorization with PKCE
`/oauth/authorize/request`	GET	Fetch a pending authorization request by `request_id` (used by the consent UI)
`/oauth/token`	POST	Code exchange and refresh token rotation
`/oauth/revoke`	POST	RFC 7009 token revocation

MCP server card

MCP clients can discover SocialAPI as a tool provider via the server card:

GET /.well-known/mcp/server-card.json

The protected resource metadata (RFC 9470) is available at:

GET /.well-known/oauth-protected-resource
GET /.well-known/oauth-protected-resource/mcp

Getting Started

Core Concepts

Connecting platform accounts

Step 1: Initiate the connection

Step 2: User authorizes on the platform

Step 3: Receive the result at your `redirect_uri`

Fallback when `redirect_uri` is omitted

Whitelisting redirect URIs

Correlation `state` (customer-controlled)

Listing connected accounts

Reconnecting an account

Disconnecting an account

OAuth 2.1 for MCP and API clients

Discovery

Step 1: Register a client

Step 2: Authorize the user

Step 3: Exchange the code for tokens

Step 4: Refresh the access token

Revoking tokens

Supporting endpoints

MCP server card

​Connecting platform accounts

​Step 1: Initiate the connection

​Step 2: User authorizes on the platform

​Step 3: Receive the result at your redirect_uri

​Google: connecting a login with multiple Business Profiles

​Fallback when redirect_uri is omitted

​Whitelisting redirect URIs

​Correlation state (customer-controlled)

​Listing connected accounts

​Reconnecting an account

​Disconnecting an account

​OAuth 2.1 for MCP and API clients

​Discovery

​Step 1: Register a client

​Step 2: Authorize the user

​Step 3: Exchange the code for tokens

​Step 4: Refresh the access token

​Revoking tokens

​Supporting endpoints

​MCP server card

Connecting platform accounts

Step 1: Initiate the connection

Step 2: User authorizes on the platform

Step 3: Receive the result at your `redirect_uri`

Google: connecting a login with multiple Business Profiles

Fallback when `redirect_uri` is omitted

Whitelisting redirect URIs

Correlation `state` (customer-controlled)

Listing connected accounts

Reconnecting an account

Disconnecting an account

OAuth 2.1 for MCP and API clients

Discovery

Step 1: Register a client

Step 2: Authorize the user

Step 3: Exchange the code for tokens

Step 4: Refresh the access token

Revoking tokens

Supporting endpoints

MCP server card