Should I Migrate to Instagram API with Unified Login?
The short answer
Migrate to Instagram API with Unified Login if you need new Instagram capabilities or want customers to connect without a linked Facebook Page; keep a working older integration while you validate the transition. Meta has not announced a retirement date for the existing setups, so decide on the features you need and on migration readiness.
When we moved Adeli to Unified Login in October 2026, we changed new connections first and kept the earlier methods for stored connections. That let us implement a reconnect path without requiring every customer to authorize again on release day.
If you need the terminology first, read what Unified Login is. The integration tutorial covers the configuration and requests; this post helps you decide when to move and what to protect.
Who needs to migrate to Unified Login?
New apps should use Unified Login, while existing apps can schedule migration around feature needs and compatibility. Meta's Instagram Login migration guide says newly created apps cannot set up Instagram Login. A new build following an old Instagram Login tutorial needs a different starting point.
For existing integrations, check two things:
- Feature direction. Meta's Unified Login overview reserves new Instagram API features for Unified Login. A feature roadmap that depends on those additions needs migration work.
- Existing access. Meta's migration overview states: "This documentation does not announce a retirement date for existing Instagram API setups."
That sentence does not guarantee indefinite support, and it does not justify telling customers their accounts will stop working on a date Meta has not announced. Separate any cutoff you choose for your own application from Meta's product policy.
A team using Adeli can use Adeli's Instagram API without owning the Meta configuration or review process. A team keeping a direct integration needs to assess the token, identifiers, and event flow together.
How do the three Instagram API setups compare?
Unified Login uses portfolio-owned authorization, Instagram Login uses Instagram User tokens, and the older Facebook Login setup reaches Instagram through a linked Page. The table follows Meta's overview and migration comparison.
| Component | Unified Login | Instagram Login | Instagram API with Facebook Login |
|---|---|---|---|
| Sign-in choices | Instagram and Facebook | ||
| Portfolio requirement | Required | Not required | Depends on configuration |
| Facebook Page dependency | None | None | Linked Page required |
| Primary token | Business Integration System User Access Token | Instagram User access token | Facebook User or Page access token |
| Permission family | instagram_* |
instagram_business_* |
instagram_* with Page permissions |
| Request host | graph.facebook.com |
graph.instagram.com |
graph.facebook.com |
| Account discovery | /me/assigned_instagram_accounts |
Token result or Instagram /me |
Linked Page relationship |
| Primary request identity | Explicit Instagram professional account ID | Instagram account ID or /me |
Page ID or /me, depending on operation |
| Consent configuration | Login URL with config_id |
Business Login for Instagram | Facebook Login for Business |
Do not apply the request-identity row as a universal rule for every older endpoint. Inventory the actual calls. Publishing already addresses an Instagram account in many Facebook Login integrations, while their messaging resolver may use the Page ID.
Unified Login is itself built on Facebook Login for Business. What changes is the configuration and the authorization it produces. Facebook in the login URL does not, by itself, mean you are on the older setup.
What changes in tokens, permissions, and account discovery?
Unified Login changes which credential you store and how you identify the accounts it authorizes. Treat those as storage and routing changes before replacing the customer-facing button.
Token lifetime becomes a configuration decision
The authentication documentation describes a Business Integration System User Access Token owned by the customer's portfolio. Expiration comes from the configuration; the credential can also stop working when the customer removes your app or moves the account to another portfolio.
An Instagram Login refresh job cannot be carried over unchanged. Adeli selected a non-expiring configuration, represented its expiry as null, and marked token-invalid connections for reconnection instead of trying an OAuth refresh. Meta also offers a separate BISU token-management API; that path means extra implementation work.
Check background jobs as well as the login callback. In our implementation, a profile-refresh query had required expiry to be in the future. We changed that condition to include connections with a null expiry, so the new token model did not exclude accounts from routine refreshes.
Permission names and review must match the new setup
For an Instagram Login migration, Meta's permissions mapping is explicit:
| Instagram Login grant | Unified Login equivalent |
|---|---|
instagram_business_basic |
instagram_basic |
instagram_business_content_publish |
instagram_content_publish |
instagram_business_manage_comments |
instagram_manage_comments |
instagram_business_manage_messages |
instagram_manage_messages |
instagram_business_manage_insights |
instagram_manage_insights |
Check Advanced Access by permission name. Existing Advanced Access to the instagram_* grants from Facebook Login carries over. Approval for a similarly named instagram_business_* grant is a different permission, so review the equivalents before inviting customers.
Saving the configuration gives Standard Access for app-role testing. Outside customers require Advanced Access and Live mode. Submit review evidence for the features you will expose, and don't request every permission the default configuration offers.
Account selection replaces assumptions about the signed-in user
With Unified Login, /me represents the system user. Read client_business_id for the portfolio, then discover shared Instagram account IDs through /me/assigned_instagram_accounts and follow pagination.
A token can cover multiple shared accounts. Decide whether your product has an account picker, a single-account rule, or several account records per customer. Never publish for whichever account happens to come first in the list.
What changes in webhooks and the inbox?
Unified Login needs its own account subscriptions, and Instagram Login message IDs cannot be reused after migration. Meta's Instagram Login migration guide documents both changes, including possible duplicate messaging notifications while two authorizations coexist.
Plan for five changes:
- Configure the Meta app receiver. Unified Login uses the Instagram object's callback on the Meta app. Your existing server can handle both setups if its verification and parsing support them.
- Subscribe the new authorization. Call
/{ig-user-id}/subscribed_appson Facebook Graph with the new token and required fields. Dashboard configuration alone is not an account subscription. - Test payload handling. Meta says Unified Login follows the Facebook Login for Business notification format. Check fixtures and real delivery against your parser.
- Rebuild message references. Discard or segregate incompatible message identifiers before reading new inbox history.
- Handle overlap safely. Duplicate deliveries must not trigger duplicate replies, automations, or other customer-visible actions.
Account identity and message identity are separate migration problems. An account may map to the same local connection while its stored inbox needs rebuilding. Tell customers before they reconnect.
For teams embedding an inbox, Adeli's messaging API provides received messages and replies. If you maintain the provider connection yourself, your team owns the event transition and the recovery when consent changes.
Which capabilities can block migration?
Keep Instagram Login if your application depends on a capability Meta lists as unsupported by Unified Login. The Instagram Login migration guide names these limitations:
| Dependency | Migration consequence |
|---|---|
| Handover Protocol | Retain the compatible setup while that dependency remains |
| Converting a personal account during login | Ask the customer to switch to a professional account in Instagram before connecting |
| Signing in through the Instagram app | Prepare customers for browser-based Instagram login and entering their password |
| App Dashboard API integration helper | Validate requests directly with the system-user token |
The API integration helper may reject system-user tokens during testing. Meta's troubleshooting guide says the helper supports Instagram User access tokens, so a rejection there doesn't prove the new integration is broken.
Business Discovery was another difference in our implementation. Adeli's earlier Instagram Login path did not support the lookup; we widened the existing Facebook-host implementation to Unified Login connections. That took a code change on our side. New features do not appear in your application just because a customer authorized Unified Login.
Should I migrate now or wait?
Start migration when you need the benefit and the new flow is verified; delay customer cutover when a dependency or identity check remains unresolved. Judge readiness by the evidence in this table. Creating the configuration is only the first step.
| Situation | Decision | Evidence to require |
|---|---|---|
| Building a new integration | Start on Unified Login | Eligible test account, valid configuration, working end-to-end flow |
| Need a new Instagram API feature | Prioritize migration | Endpoint support and approved permissions for the feature |
| Page linking blocks customer onboarding | Evaluate moving sooner | Successful portfolio and account selection without a Page dependency |
| Already hold the matching Facebook Login grants | Test migration with less review work | Advanced Access confirmed for every requested grant |
| Depend on Handover Protocol | Keep the current compatible integration | A supported replacement or a change in Meta's documented support |
| Account discovery is empty or ambiguous | Stop cutover for that connection | Intended account returned and explicitly selected |
| Cannot verify new webhook delivery | Retain working authorization | Successful real event receipt and deduplication |
| Stable legacy feature set and no immediate need | Prepare, then schedule the move | Inventory, review plan, and customer reconnect process |
Waiting should still produce a migration inventory. Record each token type, host, account identifier, messaging node, permission, and subscription path. With those records you can estimate the real work and won't discover a Page dependency mid-rollout.
How did we implement Adeli's migration?
We added Unified Login as a distinct authorization method and upgraded matching connections in place, while preserving legacy resolution for accounts that had not reconnected. We changed the default first and left retiring the old code for later.
We made the upgrade one-way
Our connection writer allowed Unified Login to replace a legacy method and refused a legacy method replacing Unified Login. New connection launch paths all led to the new flow; stored legacy rows retained their existing host and token behavior.
For a reconnect whose Instagram account ID matched the stored one, we updated the existing row and preserved its public accountId. The preserved ID depends on that match. The plan still records a live check of cross-product ID equivalence as open, and the code replaces the row when a different account ID is supplied. Verify identity mapping before promising every customer a preserved ID.
We put reconnection beside the affected account
We added an Instagram connection is changing callout for legacy connections and an action to reconnect through the new login. The callout explained that the inbox would reload. Already-upgraded accounts did not need that notice.
The prompt went only to affected accounts and did not ask anyone to disconnect a working integration. We kept the legacy token paths available while those records remained.
We rebuilt inbox data and made overlapping events harmless
When updating a matching connection, we cleared stored conversations because the message IDs differed between login setups. The callback started an inbox warm-up after connecting so history could load again.
We attempted to remove the old Instagram Login webhook subscription using its prior token. We left an older Facebook Page subscription intact because the same Page could still serve the separate Facebook connection.
Our message webhook handler scheduled a re-sync rather than sending a reply itself, and comment ingestion deduplicated by comment ID. Those choices made overlapping provider deliveries safe for those handlers. Your downstream automations need their own idempotency check.
We kept final cleanup separate
The plan deferred removing legacy routes, credentials, and storage fields until no legacy connections remained, or an explicitly chosen application cutoff dealt with the remainder. We did not treat the new login launch as permission to delete credentials still used by stored connections.
A new default connection and a completed customer migration need separate completion checks. A customer has migrated only after they authorize and you verify identity and event delivery.
What should I verify before moving a customer?
Keep the working authorization until the replacement can make a real request and receive a real notification. Meta's migration guide describes a staged client transition with a retry path when a step fails.
- Confirm review readiness. Check Advanced Access and the production configuration's actual permissions.
- Ask the customer to reconnect. Explain portfolio selection, the account to share, and messaging access if relevant.
- Match the account. Verify the returned identity against the intended connection before replacing stored credentials.
- Subscribe and exercise features. Read the profile, test the relevant API action, and receive a webhook.
- Move traffic and clean up. Switch to the new token, reset incompatible message references, and remove obsolete authorization only when safe.
Every migrating client reconnects once because the old Instagram User token cannot authorize the new setup. Build that action into the customer journey; a background token exchange cannot perform it for them.
If your team would rather own the product features than the provider migration, Adeli's posting and scheduling API handles Instagram delivery through the same API key you use for other supported networks. If you stay direct, the Unified Login integration guide is the next step after this readiness review.