Instagram — how to connect

Posts images (required — no text-only posts) to an Instagram Business account via two OAuth paths: via a Facebook Page (add your Meta app's App ID and secret below) or directly with Instagram Login (add your Instagram app's ID and secret below). Instagram provides no API to edit or delete published media.

Instagram publishing uses Meta's Instagram Platform OAuth, in one of two variants: via a linked Facebook Page, or direct Instagram Login. Both are registered as a Meta app under the same developer console — you only need the App ID/secret pair for whichever variant(s) you'll offer.

Before you start

An Instagram Business account (Creator accounts are rejected by the publish API with a "not an Instagram Business" error) — convert it under Instagram Settings > Account type before connecting.
For the default "via Facebook Page" login: a Facebook Page with that IG Business account linked to it, and you must be an admin of the Page (the app discovers the IG account via /me/accounts, so unlinked or non-admin Pages return nothing).
A Meta developer app with the Instagram Graph API product added and instagram_content_publish / instagram_business_content_publish granted — in Development mode this only works for app admins/testers added in the Meta dashboard; posting for other accounts requires Meta App Review approval.
Media must be reachable at a public URL — Meta's servers fetch the image/video by URL rather than accepting a file upload, so localhost, password-protected, or private-bucket URLs will fail.

Step by step

1
Create a Meta app
At developers.facebook.com/apps, create a new Business-type app under your Meta Business account (or reuse an existing one).
Open
2
Set up the Facebook Page variant
In the app dashboard add the Facebook Login for Business + Instagram Graph API product, then copy the App ID and App Secret from Settings > Basic into FACEBOOK_APP_ID and FACEBOOK_APP_SECRET.
Open
3
Set up the Instagram Login (direct) variant
In the same app dashboard add the Instagram product and configure Business Login for Instagram; Meta issues a separate App ID/Secret pair for this — copy those into IG_APP_ID and IG_APP_SECRET.
Open
4
Register the redirect URI
Add social-manager's OAuth redirect URL (shown on its Connect screen) to the valid OAuth redirect URIs for whichever product(s) you configured.
5
Request permissions and submit App Review
Request instagram_basic and instagram_content_publish (plus pages_show_list for the Facebook Page variant), then submit for App Review so accounts beyond app admins/testers can be connected.
Open
6
Save the keys and connect
Paste the App ID/secret pair(s) into social-manager's config, then click Connect and complete the OAuth popup to link the real Instagram Business account — no token is pasted manually.

App keys (set once in Settings)

Facebook App ID (client ID)
For the "via Facebook Page" login (IG Business account linked to a Page). developers.facebook.com → your app → Settings → Basic → App ID. Same value you'd use for Facebook.
Facebook App secret (client secret)secret
Same app → Settings → Basic → App Secret (click Show). Only needed for the "via Facebook Page" login.
Instagram App ID (client ID)
For the "Instagram direct" login (no Facebook Page). Add the Instagram product to the app → API setup with Instagram login → the SEPARATE "Instagram app ID" (not the Facebook App ID above).
Instagram App secret (client secret)secret
Same Instagram product panel → "Instagram app secret". Distinct from the Facebook App secret, even in the same console.

Good to know

Only Instagram Business or Creator accounts can be connected — personal accounts are not supported.
The Facebook Page variant requires the Instagram account to already be linked to a Facebook Page you admin.
The Instagram Login (direct) variant needs its OWN Instagram App ID/secret — it is separate from the Facebook app keys, even though both are created in the same developer console.
App Review approval is required before non-admin/tester Instagram accounts can authorize the app; until then only accounts added as testers in the app dashboard will work.
Instagram's Graph API provides no endpoint to edit or delete already-published media, and content publishing is rate-limited (historically 25 posts per rolling 24 hours per account) — verify current limits in the docs before relying on them.

Troubleshooting

Publish fails with "(#10) Application does not have permission for this action": The connected token is missing the instagram_content_publish (or instagram_business_content_publish on the Instagram-login path) scope. Disconnect and reconnect, making sure not to uncheck any requested permission during the Facebook/Instagram consent screen; if it still fails, the account needs to be added as a tester in the Meta app dashboard or the app needs App Review approval for that permission.
Connect succeeds but no Instagram account shows up ("No Instagram Business account linked to any of your Pages"): The Facebook Page isn't linked to an Instagram Business account, or it's linked to a Creator/Personal account. In the Instagram app, go to Settings > Account > Linked Accounts (or the Page's Instagram settings) and link/relink the Business account, then reconnect.
Posts fail after working fine for weeks, or token suddenly invalid: On the Instagram-direct (no Page) path, tokens are 60-day and must be refreshed before they expire (this adapter refreshes them automatically, but only if reconnect/refresh runs before expiry). On the Facebook-Page path, the long-lived Page token can be invalidated if the user changes their Facebook password, revokes app access, or the Page admin removes the app under Business Integrations — reconnect via OAuth to get a fresh token.
Container creation fails with "Unsupported get request" or the media never publishes: The image_url/video_url wasn't publicly fetchable by Meta (blocked by auth, geofencing, or not yet finished uploading/transcoding), or the container's creation_id was reused/expired before media_publish ran. Confirm the media URL loads with no auth in a plain browser request, and retry container creation rather than reusing an old creation_id.

Instagram developer docs

Instagram — how to connect

Before you start

An Instagram Business account (Creator accounts are rejected by the publish API with a "not an Instagram Business" error) — convert it under Instagram Settings > Account type before connecting.

For the default "via Facebook Page" login: a Facebook Page with that IG Business account linked to it, and you must be an admin of the Page (the app discovers the IG account via /me/accounts, so unlinked or non-admin Pages return nothing).

A Meta developer app with the Instagram Graph API product added and instagram_content_publish / instagram_business_content_publish granted — in Development mode this only works for app admins/testers added in the Meta dashboard; posting for other accounts requires Meta App Review approval.

Media must be reachable at a public URL — Meta's servers fetch the image/video by URL rather than accepting a file upload, so localhost, password-protected, or private-bucket URLs will fail.

Step by step

Create a Meta app

At developers.facebook.com/apps, create a new Business-type app under your Meta Business account (or reuse an existing one).

Open

Set up the Facebook Page variant

In the app dashboard add the Facebook Login for Business + Instagram Graph API product, then copy the App ID and App Secret from Settings > Basic into FACEBOOK_APP_ID and FACEBOOK_APP_SECRET.

Open

Set up the Instagram Login (direct) variant

In the same app dashboard add the Instagram product and configure Business Login for Instagram; Meta issues a separate App ID/Secret pair for this — copy those into IG_APP_ID and IG_APP_SECRET.

Open

Add social-manager's OAuth redirect URL (shown on its Connect screen) to the valid OAuth redirect URIs for whichever product(s) you configured.

Request permissions and submit App Review

Request instagram_basic and instagram_content_publish (plus pages_show_list for the Facebook Page variant), then submit for App Review so accounts beyond app admins/testers can be connected.

Open

Save the keys and connect

Paste the App ID/secret pair(s) into social-manager's config, then click Connect and complete the OAuth popup to link the real Instagram Business account — no token is pasted manually.

App keys (set once in Settings)

Facebook App ID (client ID)

For the "via Facebook Page" login (IG Business account linked to a Page). developers.facebook.com → your app → Settings → Basic → App ID. Same value you'd use for Facebook.

Facebook App secret (client secret)secret

Same app → Settings → Basic → App Secret (click Show). Only needed for the "via Facebook Page" login.

Instagram App ID (client ID)

For the "Instagram direct" login (no Facebook Page). Add the Instagram product to the app → API setup with Instagram login → the SEPARATE "Instagram app ID" (not the Facebook App ID above).

Instagram App secret (client secret)secret

Same Instagram product panel → "Instagram app secret". Distinct from the Facebook App secret, even in the same console.

Good to know

Only Instagram Business or Creator accounts can be connected — personal accounts are not supported.

The Facebook Page variant requires the Instagram account to already be linked to a Facebook Page you admin.

The Instagram Login (direct) variant needs its OWN Instagram App ID/secret — it is separate from the Facebook app keys, even though both are created in the same developer console.

App Review approval is required before non-admin/tester Instagram accounts can authorize the app; until then only accounts added as testers in the app dashboard will work.

Instagram's Graph API provides no endpoint to edit or delete already-published media, and content publishing is rate-limited (historically 25 posts per rolling 24 hours per account) — verify current limits in the docs before relying on them.

Troubleshooting

Publish fails with "(#10) Application does not have permission for this action"

The connected token is missing the instagram_content_publish (or instagram_business_content_publish on the Instagram-login path) scope. Disconnect and reconnect, making sure not to uncheck any requested permission during the Facebook/Instagram consent screen; if it still fails, the account needs to be added as a tester in the Meta app dashboard or the app needs App Review approval for that permission.

Connect succeeds but no Instagram account shows up ("No Instagram Business account linked to any of your Pages")

The Facebook Page isn't linked to an Instagram Business account, or it's linked to a Creator/Personal account. In the Instagram app, go to Settings > Account > Linked Accounts (or the Page's Instagram settings) and link/relink the Business account, then reconnect.

Posts fail after working fine for weeks, or token suddenly invalid

On the Instagram-direct (no Page) path, tokens are 60-day and must be refreshed before they expire (this adapter refreshes them automatically, but only if reconnect/refresh runs before expiry). On the Facebook-Page path, the long-lived Page token can be invalidated if the user changes their Facebook password, revokes app access, or the Page admin removes the app under Business Integrations — reconnect via OAuth to get a fresh token.

Container creation fails with "Unsupported get request" or the media never publishes

The image_url/video_url wasn't publicly fetchable by Meta (blocked by auth, geofencing, or not yet finished uploading/transcoding), or the container's creation_id was reused/expired before media_publish ran. Confirm the media URL loads with no auth in a plain browser request, and retry container creation rather than reusing an old creation_id.