Social Authorization

Enable users to connect their social media profiles, company pages, and groups to Oktopost from within your application.

Social authorization allows you to build a seamless experience for users to connect their social media accounts to Oktopost without leaving your application. This endpoint enables you to initiate the OAuth flow, handle callbacks, and complete the connection of social profiles, pages, and groups.

Partner Access Required

Social authorization endpoints are available for authorized partners building integrated experiences with Oktopost. Contact our partnerships team for access.

How It Works

The social authorization flow consists of three main steps:

Request authorization URL - Your app requests a redirect URL from Oktopost
User authenticates - User is redirected to the social network to authorize access
Verify and complete - User returns to your app, you verify the result and complete the connection

Supported Networks

You can initiate social authorization for the following networks:

Twitter (X)
Facebook
LinkedIn
YouTube
Instagram

Step 1: Get Authorization URL

Request a redirect URL that will initiate the OAuth flow for a specific social network.

Parameters

Parameter	Type	Required	Description
network	String	Yes	The social network to connect. Options: `Twitter`, `Facebook`, `LinkedIn`, `YouTube`, `Instagram`
url	String	Yes	The callback URL to redirect users to after authentication completes
type	String	No	The entity type to connect. Options: `profile` (default), `page`, `group`

Request

curl -u ACCOUNT_ID:API_KEY \
  https://api.oktopost.com/v2/social-authorization -X POST \
  -d network="LinkedIn" \
  -d url="https://yourapp.com/callback" \
  -d type="profile"

Response

{
	"Result": true,
	"RedirectUrl": "https://www.linkedin.com/oauth/v2/authorization?response_type=code&client_id=..."
}

After receiving the redirect URL, send the user to that URL to begin the OAuth authorization flow with the social network.

Step 2: Handle Callback

Once the user completes authorization on the social network, they'll be redirected back to the callback URL you specified. The URL will include an okt query parameter containing a verification token.

Example Callback URL

https://yourapp.com/callback?okt=591c6053d81978.11578446867279657339b29ad2799b11ca4ff883

Extract the okt token value and use it in the next step to verify the authorization result.

Step 3: Verify Authorization Result

Use the token from the callback to verify the authorization and retrieve information about the connected account.

The response format varies depending on the entity type (profile, page, or group) specified in the initial request.

Request

curl -u ACCOUNT_ID:API_KEY \
  https://api.oktopost.com/v2/social-authorization/591c6053d81978.11578446867279657339b29ad2799b11ca4ff883

Response: Profile

When connecting a personal profile, the response confirms the profile is connected and ready to use.

{
    "Result": true,
    "Credential": {
        "Id": "003-001000000000000-10795428XXXXXXXXX",
        "Created": "2000-12-31 23:59:59",
        "Name": "John Doe's Twitter",
        "Status": "valid",
        "Network": "Twitter",
        "ImageLink": "https://pbs.twimg.com/profile_images/...",
        "NetworkUsername": "johndoe"
    }
}

Response: Pages and Groups

When connecting pages or groups, the response lists all available entities the user can add to Oktopost. Present this list to the user and let them select which pages/groups to connect.

{
    "Result": true,
    "token": "591c6053d81978.11578446867279657339b29ad2799b11ca4ff883",
    "data": [
        {
            "Id": "10795428XXXXXXXXX",
            "Name": "Acme Inc",
            "Network": "Facebook",
            "ImageLink": "https://graph.facebook.com/.../picture",
            "NetworkUsername": "acmeinc",
            "IsConnected": true
        },
        {
            "Id": "20895529XXXXXXXXX",
            "Name": "Acme Products",
            "Network": "Facebook",
            "ImageLink": "https://graph.facebook.com/.../picture",
            "NetworkUsername": "acmeproducts",
            "IsConnected": false
        }
    ]
}

Response Fields

Field	Description
IsConnected	Indicates if this page/group is already connected to Oktopost
token	Authorization token needed to complete the connection in the next step
NetworkUsername	The unique username or ID on the social network

Step 4: Complete Page/Group Connection

For pages and groups, after the user selects which entities to connect, submit the selected IDs back to Oktopost to complete the connection.

Parameters

Parameter	Type	Required	Description
ids	String	Yes	Comma-separated list of page/group IDs to connect (from the `Id` field in the verification response)

Request

curl -u ACCOUNT_ID:API_KEY \
  "https://api.oktopost.com/v2/social-authorization/591c6053d81978.1157844686727965733a45fd2799b1?ids=123456,2343257" \
  -X PUT

Response

{
	"Result": true,
	"Credentials": [
		{
			"Id": "003-001000000000000-123456",
			"Name": "Acme Inc",
			"Status": "valid",
			"Network": "Facebook"
		},
		{
			"Id": "003-001000000000000-2343257",
			"Name": "Acme Products",
			"Status": "valid",
			"Network": "Facebook"
		}
	]
}

Implementation Example

Here's a simplified example of implementing the full flow:

// Step 1: Get authorization URL
async function initiateAuth(network, callbackUrl) {
  const response = await fetch('https://api.oktopost.com/v2/social-authorization', {
    method: 'POST',
    headers: {
      'Authorization': 'Basic ' + Buffer.from('ACCOUNT_ID:API_KEY').toString('base64')
    },
    body: new URLSearchParams({
      network: network,
      url: callbackUrl,
      type: 'page'
    })
  });
  
  const data = await response.json();
  // Redirect user to data.RedirectUrl
  window.location.href = data.RedirectUrl;
}

// Step 2: Handle callback
function handleCallback() {
  const urlParams = new URLSearchParams(window.location.search);
  const token = urlParams.get('okt');
  return token;
}

// Step 3: Verify authorization
async function verifyAuth(token) {
  const response = await fetch(`https://api.oktopost.com/v2/social-authorization/${token}`, {
    headers: {
      'Authorization': 'Basic ' + Buffer.from('ACCOUNT_ID:API_KEY').toString('base64')
    }
  });
  
  return await response.json();
}

// Step 4: Complete connection (for pages/groups)
async function connectPages(token, pageIds) {
  const response = await fetch(
    `https://api.oktopost.com/v2/social-authorization/${token}?ids=${pageIds.join(',')}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Basic ' + Buffer.from('ACCOUNT_ID:API_KEY').toString('base64')
      }
    }
  );
  
  return await response.json();
}

Best Practices

Handle errors gracefully: Users may deny authorization or encounter network issues
Show clear UI: Present available pages/groups with clear selection options
Respect user choice: Allow users to select which pages/groups to connect
Check connection status: Use the IsConnected field to indicate already-connected entities
Store credentials securely: Save the credential IDs for future API calls

Security Considerations

Validate callback URLs: Only redirect to whitelisted callback URLs in your application
Use HTTPS: All requests and callbacks must use HTTPS
Token expiration: Authorization tokens expire after a short period; complete the flow promptly
Secure token storage: Never expose tokens in client-side code or logs

On this page