“Rome wasn't Built in a Day and neither was your Brand Image”
Stay Consistent with PostPilot - Your AI Social Media Copilot
Social Connections
Connect your social accounts via OAuth and manage token health.
Overview
Social connections are the bridge between PostPilot and your social media accounts. Through secure OAuth authentication, PostPilot connects to Instagram, Facebook, LinkedIn, Twitter, and TikTok, enabling automated publishing and analytics retrieval without ever storing your passwords.
Each connection is associated with a specific organization and grants PostPilot the minimum permissions necessary to publish content and read basic analytics on your behalf. You retain full control and can revoke access at any time from either PostPilot or the social platform's own settings.
Maintaining healthy connections is essential for uninterrupted publishing. This guide covers the initial connection flow, how to monitor connection health, the automatic token refresh system, and steps for troubleshooting common issues.
Connecting an Account
Connecting a social media account to PostPilot follows a standard OAuth flow. The process is the same for all supported platforms, though the specific permissions requested vary by platform.
Go to Settings > Connections
From the navigation menu, click on Settings and then select Connections. This page displays all currently connected accounts and provides buttons to add new connections for each supported platform.
Select the platform to connect
Click the connect button for the social platform you want to add. PostPilot supports Instagram (via Facebook Business), Facebook Pages, LinkedIn (personal and company pages), Twitter, and TikTok. Each platform button shows the permissions that will be requested.
Authorize in the platform popup
A popup window opens directing you to the social platform's authorization page. Log in with your account credentials if prompted, review the permissions PostPilot is requesting, and click authorize or allow. The popup closes automatically upon successful authorization.
Verify the connection
After authorization, the Connections page updates to show the newly connected account with a green health indicator. PostPilot performs a test API call to verify that the connection is working correctly. The account name, profile picture, and connection date are displayed for confirmation.
For Instagram, you must connect through a Facebook Business account that is linked to your Instagram Professional account. If you have a personal Instagram account, you will need to convert it to a Professional (Business or Creator) account first through the Instagram app settings.
Connection Health
PostPilot continuously monitors the health of your social connections to ensure they are ready for publishing at all times. Each connection displays a health indicator that reflects its current status.
Green (Healthy): The connection is active and fully functional. API calls are succeeding and the access token is valid. No action is required.
Yellow (Warning): The connection is functional but the access token is approaching expiration. PostPilot will attempt automatic refresh, but if the refresh fails, manual reconnection may be needed soon.
Red (Disconnected): The connection has failed. The access token has expired and could not be refreshed, or the user revoked access on the platform side. Reconnection is required before any content can be published to this account.
PostPilot checks connection health automatically every few hours. You can also trigger a manual health check by clicking the refresh icon next to any connection on the Connections settings page.
Token Refresh
Social platform access tokens have limited lifespans. Facebook and Instagram tokens typically last 60 days, LinkedIn tokens last 60 days, Twitter tokens vary by authentication type, and TikTok tokens last 24 hours with a longer-lived refresh token.
PostPilot handles token refresh automatically through a scheduled cron job that runs at regular intervals. The refresh cron checks all connections, identifies tokens that are nearing expiration, and uses the platform's refresh token mechanism to obtain new access tokens without requiring any user interaction.
The refresh process is transparent. When a token is successfully refreshed, the connection health indicator remains green and you will not notice any interruption. If a refresh fails, the connection status changes to yellow or red depending on the severity, and you will be notified to take action.
If you change your password on a social platform or revoke PostPilot's access from the platform's app settings, the automatic token refresh will fail. You will need to reconnect the account manually through PostPilot's Connections settings.
Reconnecting
When a connection enters a disconnected state and automatic refresh cannot recover it, you will need to reconnect the account manually. The reconnection process is straightforward and preserves all of your existing post history and settings for that account.
Navigate to Settings > Connections
Go to the Connections page where you will see the affected account with a red health indicator. A "Reconnect" button appears next to disconnected accounts.
Click Reconnect
Click the Reconnect button to initiate a new OAuth flow. This opens the same authorization popup as the initial connection. Log in and authorize PostPilot again. The existing connection record is updated with the new tokens rather than creating a duplicate.
Verify the restored connection
After authorization, the health indicator should return to green. PostPilot runs a verification API call to confirm the connection is working. Any posts that were scheduled during the disconnection period may need to be rescheduled.
Troubleshooting
Connection issues can arise from several common causes. Here are the most frequent problems and their solutions to help you get back up and running quickly.
OAuth popup blocked: If the authorization popup does not appear, your browser may be blocking popups. Allow popups for the PostPilot domain in your browser settings and try again. Some ad blockers also interfere with OAuth flows, so temporarily disabling them may help.
Insufficient permissions: If publishing fails even though the connection appears healthy, you may not have granted all necessary permissions during authorization. Disconnect the account and reconnect, making sure to accept all requested permissions in the authorization dialog.
Account type mismatch: Instagram requires a Professional account (Business or Creator) linked to a Facebook Business page. Personal accounts cannot be connected. LinkedIn company page publishing requires admin access to the company page.
Rate limiting: Social platforms impose API rate limits. If you are publishing a high volume of content in a short period, you may encounter temporary failures. PostPilot automatically retries with exponential backoff, but sustained high-volume publishing may require spacing out your posts.
If you continue to experience connection issues after trying the steps above, check the platform's developer status page for any ongoing API outages. You can also reach out to PostPilot support for assistance with persistent connection problems.