How to get and refresh an Instagram access token

Which Instagram access token do you need?

Instagram token types and lifetimes

Even a non-expiring Page token can be invalidated under certain conditions — the error 190 subcodes below show the typical reasons.

Instagram Login: from code to long-lived token

1. 1

   Send the user to the login dialog

   Redirect to https://www.instagram.com/oauth/authorize with client_id, redirect_uri, response_type=code, a comma-separated scope (e.g. instagram_business_basic,instagram_business_manage_messages) and a random state.

2. 2

   Receive the code

   Instagram redirects back to redirect_uri with ?code=...; the trailing #_ is not part of the code, so strip it. The code is valid for 1 hour and can be used once.

3. 3

   Exchange it for a short-lived token

   POST the form fields client_id, client_secret, grant_type=authorization_code, redirect_uri and code to https://api.instagram.com/oauth/access_token. The response holds the short-lived token, the user_id and the granted permissions.

4. 4

   Get a long-lived token

   GET https://graph.instagram.com/access_token with grant_type=ig_exchange_token, client_secret and access_token. expires_in is roughly 5,184,000 seconds — 60 days.

5. 5

   Store it with its expiry

   Save the token encrypted together with expires_at (now + expires_in). The refresh job will need that date.

The same flow with the Socialift SDK

import os
from socialift import Instagram

async def instagram_callback(code: str, state: str, expected_state: str) -> dict:
    if state != expected_state:
        raise ValueError("state mismatch")  # CSRF protection
    async with Instagram.from_env() as ig:
        bundle = await ig.exchange_code(code, redirect_uri=os.environ["IG_REDIRECT_URI"])
        profile = await ig.profile(bundle.access_token)
    return {
        "username": profile.username,
        "token": bundle.access_token,     # encrypt before saving
        "expires_at": bundle.expires_at,  # about 60 days from now
    }

How do you refresh an Instagram long-lived token?

A token refresh job

from datetime import datetime, timedelta, timezone
from socialift import AuthError, Instagram

async def refresh_instagram_tokens(accounts) -> None:
    soon = datetime.now(timezone.utc) + timedelta(days=10)
    async with Instagram.from_env() as ig:
        for acc in accounts:  # rows from your own database
            if acc.expires_at > soon:
                continue
            try:
                bundle = await ig.refresh_token(acc.token)
            except AuthError:
                acc.status = "reconnect_required"  # expired or revoked
                continue
            acc.token, acc.expires_at = bundle.access_token, bundle.expires_at

Facebook Login: user token → Page token → Instagram account ID

1. 1

   Log in with Facebook

   Send the user through Facebook Login (for Business apps, with a configuration ID) and request instagram_basic, pages_show_list and the permissions your feature needs.

2. 2

   Exchange the code

   GET /oauth/access_token on graph.facebook.com with client_id, client_secret, redirect_uri and code returns a short-lived user token that expires within hours.

3. 3

   Get a long-lived user token

   Call the same endpoint with grant_type=fb_exchange_token, client_id, client_secret and fb_exchange_token. The result generally lasts about 60 days.

4. 4

   List Pages and their tokens

   GET /me/accounts with the long-lived user token returns the Pages where the user can perform MANAGE, CREATE_CONTENT, MODERATE or ADVERTISE, each with an access_token. Page tokens obtained this way have no expiration date.

5. 5

   Find the Instagram account

   GET /{page-id}?fields=instagram_business_account returns the ID of the linked Instagram professional account — the ID you use in every Instagram call.

6. 6

   Call Instagram endpoints

   Send requests to graph.facebook.com/{version}/<IG_ID>/... with the Page token.

The Facebook Login flow with the SDK

import os
from socialift import Facebook, Instagram

async def facebook_callback(code: str) -> list[dict]:
    async with Facebook.from_env() as fb:
        user = await fb.exchange_code(code, redirect_uri=os.environ["FB_REDIRECT_URI"])
        print("granted:", await fb.granted_scopes(user.access_token))
        pages = await fb.pages(user.access_token)

    accounts = [p for p in pages if p.instagram_id]
    async with Instagram.via_facebook(app_secret=os.environ["FACEBOOK_APP_SECRET"]) as ig:
        for page in accounts:
            profile = await ig.profile(page.access_token, ig_user_id=page.instagram_id)
            print(page.name, "->", profile.username)
    return [{"page_id": p.id, "ig_user_id": p.instagram_id, "page_token": p.access_token} for p in accounts]

How do you debug an Instagram access token?

Error 190 and other token errors

In the Socialift SDK codes 190 and 102 raise AuthError, codes 10 and 200–299 raise PermissionError; both carry code and subcode from Meta's response.

How to store Instagram tokens safely

In the Socialift dashboard, OAuth tokens of connected accounts are encrypted on the server and never sent to the browser. Apply the same rules in your own backend:

• ▸Keep the app secret and every token exchange on the server; the secret never reaches a browser or mobile app.
• ▸Store tokens encrypted at rest, each with its expires_at.
• ▸Never write tokens to logs or error trackers — log the account ID and fbtrace_id instead.
• ▸Generate a random state for every login and compare it in the callback to block CSRF.
• ▸Treat AuthError as a state change (reconnect required), not as a transient error to retry.
• ▸When a user disconnects, revoke permissions on Meta's side too (fb.revoke for Facebook Login) instead of only deleting the row.