DEV Community: Oleksandr Pohorelov

TikTok Content Publishing API: Videos, Photo Carousels & the Async Publishing Dance

Oleksandr Pohorelov — Sun, 22 Mar 2026 12:20:59 +0000

You'd think posting a video to TikTok via API would be straightforward — upload a file, set a caption, done. Instead, you initialize a publish, TikTok pulls the video from your server, and you poll for status. Oh, and if you want to post photos? No PNGs allowed.

The Problem

TikTok's Content Publishing API is fully asynchronous. There's no "upload and get a post ID back" flow. Instead:

You initialize a publish request — telling TikTok where to find your media
TikTok pulls the media from your URL (yes, your file must be publicly accessible)
You poll for status — the video goes through download, upload processing, and finally publishing
If it fails, you check the failure reason — some are retryable, some aren't

This is different from platforms like Twitter or LinkedIn where you push media directly. TikTok pulls it. That means your media hosting needs to serve files publicly, and you need to handle a state machine of publish statuses.

And then there are the surprises: TikTok doesn't accept PNG images (seriously), privacy levels must match what the creator allows, and the endpoints for video vs. photo posts are completely different.

Let's walk through all of it.

Prerequisites

A TikTok Developer App registered at developers.tiktok.com
A valid access token obtained via TikTok's OAuth 2.0 flow (authorization code + PKCE)
Required scopes: video.publish, video.upload
Media files hosted at a publicly accessible URL — TikTok will download them from your server
Videos must be MP4. Images must be JPEG or WEBP (not PNG — TikTok will reject them)

TikTok OAuth: Getting Your Access Token

Before you can publish, you need an access token. TikTok uses a standard OAuth 2.0 authorization code flow with PKCE.

Step 1 — Build the Authorization URL

Direct the user to TikTok's authorization page:

https://www.tiktok.com/v2/auth/authorize/
  ?client_key={your_client_key}
  &response_type=code
  &scope=user.info.basic,video.publish,video.upload
  &redirect_uri={your_redirect_uri}
  &state={random_state}
  &code_challenge={code_challenge}
  &code_challenge_method=S256

After the user approves, TikTok redirects to your redirect_uri with a code parameter.

Step 2 — Exchange the Code for Tokens

curl -X POST "https://open.tiktokapis.com/v2/oauth/token/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_key={your_client_key}" \
  -d "client_secret={your_client_secret}" \
  -d "code={authorization_code}" \
  -d "grant_type=authorization_code" \
  -d "redirect_uri={your_redirect_uri}" \
  -d "code_verifier={code_verifier}"

Response:

{
  "access_token": "act.xxxxxxxxxxxx",
  "expires_in": 86400,
  "open_id": "user-open-id",
  "refresh_token": "rft.xxxxxxxxxxxx",
  "refresh_expires_in": 31536000,
  "token_type": "Bearer"
}

The access token lasts about 1 day (86,400 seconds). The refresh token is valid for 365 days.

Step 3 — Refresh When Expired

curl -X POST "https://open.tiktokapis.com/v2/oauth/token/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_key={your_client_key}" \
  -d "client_secret={your_client_secret}" \
  -d "grant_type=refresh_token" \
  -d "refresh_token={refresh_token}"

Heads up: Each refresh response includes a new refresh token. Always store the latest one — the old one gets invalidated.

Step-by-Step: Publishing a Video

Video publishing uses the PULL_FROM_URL source type — you provide a URL and TikTok downloads the video from your server.

Step 1 — Query Creator Info (Optional but Recommended)

Before publishing, check what privacy levels and features the creator has access to:

curl -X POST "https://open.tiktokapis.com/v2/post/publish/creator_info/query/" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

Response:

{
  "data": {
    "creator_avatar_url": "https://...",
    "creator_username": "johndoe",
    "creator_nickname": "John",
    "privacy_level_options": ["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY"],
    "comment_disabled": false,
    "duet_disabled": false,
    "stitch_disabled": false,
    "max_video_post_duration_sec": 600
  }
}

The privacy_level_options array tells you which values you're allowed to use when publishing. If you pick a value that isn't in this list, TikTok will reject the publish request.

Step 2 — Initialize the Video Publish

curl -X POST "https://open.tiktokapis.com/v2/post/publish/video/init/" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json; charset=UTF-8" \
  -d '{
    "post_info": {
      "title": "Check out this awesome video!",
      "privacy_level": "PUBLIC_TO_EVERYONE",
      "disable_duet": false,
      "disable_comment": false,
      "disable_stitch": false,
      "video_cover_timestamp_ms": 1
    },
    "source_info": {
      "source": "PULL_FROM_URL",
      "video_url": "https://your-cdn.com/video.mp4"
    }
  }'

Response:

{
  "data": {
    "publish_id": "v_pub_xxxxxxxxxxxx"
  }
}

Important: The video_url must be publicly accessible. TikTok's servers will make an HTTP request to download the file. If it's behind auth or returns a redirect chain that TikTok can't follow, the publish will fail silently during processing.

Step 3 — Poll for Publish Status

Publishing is async. After initialization, you need to poll until TikTok finishes processing:

curl -X POST "https://open.tiktokapis.com/v2/post/publish/status/fetch/" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "publish_id": "v_pub_xxxxxxxxxxxx"
  }'

Response (processing):

{
  "data": {
    "status": "PROCESSING_DOWNLOAD"
  }
}

Response (complete):

{
  "data": {
    "status": "PUBLISH_COMPLETE"
  }
}

Response (failed):

{
  "data": {
    "status": "FAILED",
    "fail_reason": "picture_size_check_failed"
  }
}

The status progresses through these states:

Status	Meaning
`PROCESSING_DOWNLOAD`	TikTok is downloading your media
`PROCESSING_UPLOAD`	Media is being processed/transcoded
`SEND_TO_USER_INBOX`	Video sent to creator's inbox for review
`PUBLISH_COMPLETE`	Published successfully
`FAILED`	Something went wrong — check `fail_reason`

Polling strategy: Wait about 45 seconds between polls. Video processing can take a while depending on file size and TikTok's current load. Plan for up to 3 polling attempts before treating it as a timeout.

Step-by-Step: Publishing Photos

Photo posts use a different endpoint than videos and support carousels of up to 10 images.

Step 1 — Initialize the Photo Publish

curl -X POST "https://open.tiktokapis.com/v2/post/publish/content/init/" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json; charset=UTF-8" \
  -d '{
    "post_info": {
      "title": "Photo carousel post",
      "description": "Check out these shots from my trip!",
      "privacy_level": "PUBLIC_TO_EVERYONE",
      "disable_comment": false
    },
    "source_info": {
      "source": "PULL_FROM_URL",
      "photo_cover_index": 0,
      "photo_images": [
        "https://your-cdn.com/photo1.jpg",
        "https://your-cdn.com/photo2.jpg",
        "https://your-cdn.com/photo3.jpg"
      ]
    },
    "post_mode": "DIRECT_POST",
    "media_type": "PHOTO"
  }'

Step 2 — Poll for Status

Same polling flow as video — use /post/publish/status/fetch/ with the publish_id.

The PNG trap: TikTok accepts JPEG and WEBP for photos but rejects PNG. If your users upload PNGs, you need to convert them to JPEG before publishing. This is easy to miss because most other platforms accept PNG without issues. Convert on the server side before passing the URL to TikTok.

The Public URL Requirement

Unlike platforms where you push binary data directly, TikTok uses a pull model — you give TikTok a URL and their servers fetch the file. This means:

Your media must be at a publicly accessible URL — no auth headers, no short-lived pre-signed URLs that expire in seconds
The URL must resolve quickly — TikTok won't wait long for slow servers
No redirects that TikTok can't follow — keep the URL direct

If you're using S3-compatible storage (like Tigris, AWS S3, etc.), you'll need to either:

Make the file public before publishing
Use a CDN domain alias so the URL looks like https://media.yourdomain.com/video.mp4 instead of an S3 pre-signed URL

Handling Failures & Retries

Not all failures are permanent. TikTok's fail_reason values fall into two categories:

Retryable failures (try again):

rate_limit_exceeded — you're making too many requests, back off and retry

Non-retryable failures (fix the issue first):

file_format_check_failed — wrong file type (e.g., PNG instead of JPEG)
duration_check_failed — video too long or too short
frame_rate_check_failed — video frame rate out of range
picture_size_check_failed — image dimensions out of range
spam_risk_too_many_pending_share — too many pending publishes
publish_cancelled — user cancelled in the app
Various banned/restricted user errors

When you get a retryable failure, wait a few seconds and re-initialize the publish. For non-retryable failures, you'll need to fix the underlying issue (convert the file format, resize, etc.) before trying again.

Common Pitfalls

PNG images are rejected — TikTok only accepts JPEG and WEBP for photo posts. Convert PNGs to JPEG on your server before publishing
Videos use a different endpoint than photos — /post/publish/video/init/ vs /post/publish/content/init/. Don't mix them up
Privacy level must match creator's options — always query /creator_info/query/ first and use a value from the privacy_level_options array
Media URLs must be truly public — pre-signed URLs that expire quickly will fail. TikTok needs time to download the file
title is the video caption, description is for photos — the naming is confusing but post_info.title is what appears as the post text for videos
Photo posts support up to 10 images — but you can't mix photos and videos in one post
Polling takes patience — video processing can take minutes. Don't poll too aggressively or you'll hit rate limits
Access tokens expire daily — unlike Meta's 60-day tokens, TikTok tokens last only ~24 hours. Make sure your refresh logic runs frequently

TL;DR — The Full Flow (Diagram)

Video Publishing

Photo Publishing

About PostPulse

PostPulse handles all of this for you — video and photo publishing, PNG-to-JPEG conversion, public URL hosting, status polling with retry logic, and token refresh — across TikTok and 8 other platforms. Focus on creating content, not wrestling with APIs.

Try PostPulse free →

Instagram Container-Based Publishing: The 3-Step Dance for Reels, Stories & Carousels

Oleksandr Pohorelov — Tue, 17 Mar 2026 10:20:44 +0000

You can't just POST an image to Instagram and call it a day. You have to create a "container", wait for Instagram to process it, and then publish it. Oh, and carousels? That's containers inside containers.

The Problem

If you've worked with other social media APIs — Facebook, Twitter, LinkedIn — you're used to a fairly direct flow: upload media, create a post, done. Instagram is different.

Instagram uses a container-based publishing model. Instead of directly uploading and posting, you:

Create a container — tell Instagram where your media lives (a public URL) and what type of post it is
Wait for processing — Instagram downloads your media, validates it, transcodes video, generates thumbnails... and this can take minutes
Publish the container — only after processing is complete

For carousels, you create individual containers for each item first, then a parent container referencing all the children, wait for that to process, and then publish.

If you skip the wait step or try to publish a container that's still IN_PROGRESS, you'll get errors. If you don't handle the ERROR status correctly, you'll miss retryable failures. And if you don't know that VIDEO as a media type is deprecated (use REELS instead), you'll waste hours debugging.

Let's walk through all of it.

Prerequisites

A valid long-lived Instagram access token (see Part 1: Meta OAuth Token Lifecycle)
Your Instagram account's user ID (returned during authorization)
Required scope: instagram_content_publish
Media files hosted at a publicly accessible URL — Instagram will download them from your server (it won't accept direct file uploads)
Images must be JPEG or PNG. Videos must be MP4

Step-by-Step: Single Media Post

Step 1 — Create the Container

Tell Instagram about your media by creating a container. The endpoint and parameters differ by media type:

Image post:

curl -X POST "https://graph.instagram.com/v22.0/{user_id}/media" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://your-cdn.com/photo.jpg",
    "caption": "Check out this view! #travel"
  }'

Reel (video):

curl -X POST "https://graph.instagram.com/v22.0/{user_id}/media" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://your-cdn.com/video.mp4",
    "caption": "Behind the scenes 🎬",
    "media_type": "REELS",
    "cover_url": "https://your-cdn.com/thumbnail.jpg"
  }'

Story (image):

curl -X POST "https://graph.instagram.com/v22.0/{user_id}/media" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://your-cdn.com/story-photo.jpg",
    "media_type": "STORIES"
  }'

Story (video):

curl -X POST "https://graph.instagram.com/v22.0/{user_id}/media" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://your-cdn.com/story-video.mp4",
    "media_type": "STORIES"
  }'

Response (same for all):

{
  "id": "17889615691921648"
}

That id is your container ID. It's not a published post yet — it's a container that Instagram is now processing.

⚠️ Stories don't get a caption. If you pass caption with media_type: "STORIES", it's ignored. Stories are media-only.

⚠️ VIDEO is deprecated. Always use REELS for single video posts. If you send media_type: "VIDEO", the API may reject it or behave unexpectedly.

Step 2 — Poll Until the Container is Ready

Instagram needs time to download your media, validate it, and process it (especially for video). You must poll the container status before attempting to publish:

curl -G "https://graph.instagram.com/{container_id}" \
  -H "Authorization: Bearer {access_token}" \
  -d "fields=status_code,status"

Response when still processing:

{
  "status_code": "IN_PROGRESS",
  "id": "17889615691921648"
}

Response when ready:

{
  "status_code": "FINISHED",
  "id": "17889615691921648"
}

Response on error:

{
  "status_code": "ERROR",
  "status": "2207026",
  "id": "17889615691921648"
}

Polling Strategy: Exponential Backoff

Don't just hammer the endpoint every second. Use increasing delays between attempts:

Attempt 1: wait  5 seconds, then poll
Attempt 2: wait 10 seconds, then poll
Attempt 3: wait 15 seconds, then poll
...
Attempt N: wait (5 × N) seconds, then poll

Set a maximum of ~25 attempts. For images, you'll typically get FINISHED within the first few polls. For video (especially longer Reels), it can take several minutes.

Handling the ERROR Status

This is where it gets nuanced. An ERROR status doesn't always mean you should give up. The status field contains a numeric subcode that tells you what went wrong:

Retryable errors (create a new container and try again):

Subcode	Meaning
2207051	Media download timed out — Instagram couldn't fetch your file
2207052	Media expired
2207001	Server error
2207003	Failed to create media
2207016	Unknown upload error
2207027	Container not found
2207028	URI fetch failed
2207050	Media not ready

Non-retryable errors (fix the issue before retrying):

Subcode	Meaning
2207006	Suspected spam
2207024	Publish limit reached
2207009	Unknown/unsupported media type
2207010	Carousel has invalid item count
2207026	Unsupported video format
2207034	Image too large
2207035	Unsupported image format
2207042	Invalid image aspect ratio
2207048	Caption too long

When you encounter a retryable error, the right approach is to clear the container reference, wait, and create a fresh container. Don't keep polling a failed container — it won't recover.

For non-retryable errors, you need to fix the underlying issue (resize the image, change the format, shorten the caption, etc.) before retrying.

💡 Error tolerance during polling: In practice, you may see a few generic ERROR statuses before a container eventually succeeds. A reasonable approach is to tolerate up to ~5 generic errors before giving up, while immediately failing on known non-retryable subcodes.

Step 3 — Publish the Container

Once the status is FINISHED, publish it:

curl -X POST "https://graph.instagram.com/v22.0/{user_id}/media_publish" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "creation_id": "17889615691921648"
  }'

Response:

{
  "id": "17895432187654321"
}

This id is the actual published post ID — the one you'd use for fetching insights, comments, etc.

⚠️ The publish call can fail due to rate limits. Implement retry with exponential backoff on the publish step too. Instagram returns transient errors here that succeed on retry.

Step-by-Step: Carousel Post

Carousels add another layer. You need to create a container for each item, then a parent container that references all the children.

Step 1 — Create Child Containers (No Caption)

For each image or video in the carousel, create a container with is_carousel_item: true:

Image child:

curl -X POST "https://graph.instagram.com/v22.0/{user_id}/media" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://your-cdn.com/photo1.jpg",
    "is_carousel_item": true
  }'

Video child:

curl -X POST "https://graph.instagram.com/v22.0/{user_id}/media" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://your-cdn.com/video1.mp4",
    "media_type": "VIDEO",
    "is_carousel_item": true
  }'

💡 Note: Unlike single video posts where VIDEO is deprecated in favor of REELS, carousel video items still use media_type: "VIDEO".

⚠️ No caption on children. The caption goes on the parent carousel container, not on individual items.

Repeat for each item. Collect all the returned container IDs.

Step 2 — Wait for ALL Children to Finish

Poll each child container until it reaches FINISHED. All children must be ready before you can create the parent:

# Poll each child
curl -G "https://graph.instagram.com/{child_container_id}" \
  -H "Authorization: Bearer {access_token}" \
  -d "fields=status_code,status"

Step 3 — Create the Carousel Parent Container

Once all children are FINISHED, create the parent container referencing all children:

curl -X POST "https://graph.instagram.com/v22.0/{user_id}/media" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "media_type": "CAROUSEL",
    "children": "17889615691921648,17889615691921649,17889615691921650",
    "caption": "Swipe through our latest collection! ✨"
  }'

Response:

{
  "id": "17889615691921700"
}

⚠️ Children is a comma-separated string of IDs, not a JSON array. This trips people up.

Step 4 — Wait for the Carousel Container

The parent container also needs processing:

curl -G "https://graph.instagram.com/{carousel_container_id}" \
  -H "Authorization: Bearer {access_token}" \
  -d "fields=status_code,status"

Step 5 — Publish the Carousel

Same as before — publish the parent container:

curl -X POST "https://graph.instagram.com/v22.0/{user_id}/media_publish" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "creation_id": "17889615691921700"
  }'

Handling Container Expiry and Recovery

Containers don't live forever. If you create a container and don't publish it within a certain window, it expires. Your status poll will return EXPIRED, and you'll need to start over.

The right recovery strategy depends on the container type:

Single media: Clear the container reference and create a new container from scratch.

Carousel children: If a child expires, clear its reference and recreate just that child. You don't need to recreate children that already finished — unless the parent carousel itself hasn't been created yet.

Carousel parent: If the parent carousel container expires or errors, clear the carousel container ID but keep the finished children. Create a new parent container referencing the same children. If the children have also expired, you'll need to recreate those too.

This is where persistent tracking of container states pays off. For each media item, store:

The container ID returned by Instagram
The current status (IN_PROGRESS, FINISHED, ERROR, EXPIRED)
Whether it's a single item, carousel child, or carousel parent

When retrying, check what's already finished before recreating everything from scratch.

Multiple Stories

Unlike feed posts and carousels, Stories are published individually — there's no grouping mechanism. If you have 5 images to publish as Stories, you create and publish each one separately:

For each media file:
  1. Create container (media_type: "STORIES")
  2. Wait for FINISHED
  3. Publish
  4. Move to next

They'll appear in your story timeline in the order you publish them.

PNG Handling

Instagram accepts PNG images, but in practice, converting PNG to JPEG before uploading leads to more reliable results and faster processing. If your storage pipeline serves PNGs, consider converting to JPEG server-side before passing the URL to Instagram. This also reduces file size, which means faster downloads for Instagram's servers and fewer MEDIA_DOWNLOAD_TIMEOUT errors.

Common Pitfalls

Media must be at a public URL — Instagram downloads the file from the URL you provide. If it's behind authentication, a CDN with restricted access, or a pre-signed URL that's expired, you'll get a download timeout error.
VIDEO is deprecated for single posts — Use REELS as the media_type for any single video post. VIDEO still works for carousel children.
Don't skip polling — Publishing a container that's still IN_PROGRESS will fail. Always poll until FINISHED.
Stories don't support captions — The caption field is ignored for STORIES media type.
Carousel children don't get captions — Put the caption on the carousel parent container only.
The children parameter is a comma-separated string — Not a JSON array. "id1,id2,id3" not ["id1","id2","id3"].
Container IDs expire — If you create containers ahead of time (e.g., for scheduled posts), you need recovery logic in case they expire before publishing time.
Publish calls need retry logic — The media_publish endpoint is rate-limited and can return transient errors. Implement backoff-based retry.
Error subcodes matter — Don't treat all ERROR statuses the same. Some are retryable (server errors, download timeouts), others require fixing the media (wrong format, too large, bad aspect ratio).

TL;DR — The Full Flow (Diagram)

Single Media (Image/Reel/Story)

Carousel

Stop Wrestling with Instagram Containers

If your goal is to build user-facing features rather than managing complex polling loops, retry logic for 2207xxx error codes, and multi-step carousel state machines, you might want to look at PostPulse for Developers.

We built the PostPulse Social Media API to turn Instagram’s multi-step "Container" nightmare into a single POST request. Instead of managing separate flows for Reels, Stories, and Carousels, you get:

Atomic Publishing: No more polling for FINISHED status. Send us the media, and we handle the container creation, processing wait times, and final publication.
Unified Media Handling: One standard syntax for scheduling posts across 9+ platforms. We handle the "video vs. reels" deprecation logic so you don't have to.
Automatic Retries: If Instagram throws a retryable subcode (like a media download timeout), our system handles the backoff and recovery automatically.
Bypass App Review: Use our pre-approved Meta, LinkedIn, and TikTok integrations to go live in hours, not weeks.

Don't waste engineering sprints on social media infrastructure. Try the PostPulse API for free →

Meta OAuth: Short-Lived vs Long-Lived Tokens (and Why Your Token Expires After 1 Hour)

Oleksandr Pohorelov — Sun, 15 Mar 2026 08:54:30 +0000

You got a token from Facebook Login, everything works, and then exactly 1 hour later, your app goes dark. Sound familiar?

The Problem

Here's what trips up almost every developer integrating with Facebook, Instagram, or Threads for the first time: you complete the OAuth flow, get a shiny access token, make a few API calls, and everything is fine — until it isn't. An hour later, your calls start returning OAuthException errors, and you're staring at your code, wondering what went wrong.

The answer? Meta issues a short-lived token by default. It's valid for about 1–2 hours, and most tutorials end there. What they don't tell you is that there's a second exchange step to get a long-lived token (valid for 60 days), and a third step to refresh that long-lived token before it expires.

Let's walk through the full lifecycle across Facebook, Instagram, and Threads.

Prerequisites

Before you start, make sure you have:

A Facebook App created at Meta for Developers
App ID (client_id) and App Secret (client_secret)
For Instagram/Threads: the appropriate product has been added to your Meta App.
OAuth redirect URI configured in your app settings.
Required permissions/scopes:
Facebook: pages_manage_posts, pages_read_engagement, public_profile
Instagram: instagram_basic, instagram_content_publish
Threads: threads_basic, threads_content_publish

Step-by-Step

Step 1 — Get an Authorization Code

Direct the user to the platform-specific authorization URL:

Facebook:

https://www.facebook.com/v23.0/dialog/oauth
?client_id={app_id}  
&redirect_uri={your_redirect_uri}  
&scope=pages_manage_posts,pages_read_engagement,public_profile  
&response_type=code  
&state={csrf_token}

Instagram:

https://api.instagram.com/oauth/authorize  
?client_id={app_id}  
&redirect_uri={your_redirect_uri}  
&scope=instagram_basic,instagram_content_publish  
&response_type=code  &state={csrf_token}

Threads:

https://www.threads.com/oauth/authorize  
?client_id={app_id}  
&redirect_uri={your_redirect_uri}  
&scope=threads_basic,threads_content_publish  
&response_type=code  
&state={csrf_token}

After the user grants permissions, Meta redirects back with a code parameter. This code is single-use and expires in about 10 minutes.

Step 2 — Exchange the Code for a Short-Lived Token

Facebook:

curl -X POST "https://graph.facebook.com/v23.0/oauth/access_token" \  
-d "code={authorization_code}" \  
-d "grant_type=authorization_code" \  
-d "client_id={app_id}" \  
-d "redirect_uri={your_redirect_uri}" \  
-d "client_secret={app_secret}"

Instagram:

curl -X POST "https://api.instagram.com/oauth/access_token" \  
-d "code={authorization_code}" \  
-d "grant_type=authorization_code" \  
-d "client_id={app_id}" \  
-d "redirect_uri={your_redirect_uri}" \  
-d "client_secret={app_secret}"

Threads:

curl -X POST "https://graph.threads.net/oauth/access_token" \  
-d "code={authorization_code}" \  
-d "grant_type=authorization_code" \  
-d "client_id={app_id}" \  
-d "redirect_uri={your_redirect_uri}" \  
-d "client_secret={app_secret}"

Response:

{
"access_token": "EAAG...short-lived-token...", 
"token_type": "bearer", 
"expires_in": 3600
}

⚠️ This is the short-lived token. It expires in ~1 hour. If you stop here, your integration will break every 60 minutes. Don’t stop here.

Step 3 — Exchange Short-Lived Token for Long-Lived Token

This is the step most tutorials skip. You take the short-lived token from Step 2 and exchange it for a long-lived one:

Facebook:

curl -X POST "https://graph.facebook.com/v23.0/oauth/access_token" \  
-d "grant_type=fb_exchange_token" \  
-d "client_id={app_id}" \  
-d "client_secret={app_secret}" \  
-d "fb_exchange_token={short_lived_token}"

Instagram:

curl -G "https://graph.instagram.com/access_token" \  
-d "grant_type=ig_exchange_token" \  
-d "client_secret={app_secret}" \  
-d "access_token={short_lived_token}"

Threads:

curl -G "https://graph.threads.net/access_token" \  
-d "grant_type=th_exchange_token" \  
-d "client_secret={app_secret}" \  
-d "access_token={short_lived_token}"

Response:

{
"access_token": "EAAG...long-lived-token...", 
"token_type": "bearer", 
"expires_in": 5184000
}

That 5184000 is 60 days in seconds. You just went from 1 hour to 60 days.

⚠️ Notice the different grant types: Facebook uses fb_exchange_token, while Instagram uses ig_exchange_token, and Threads uses th_exchange_token. They’re the same concept but different parameter values. Mix them up, and you’ll get an unhelpful error.

Step 4 — Refresh the Long-Lived Token (Before It Expires)

Long-lived tokens can be refreshed for another 60 days. But there are conditions:

The token must be at least 24 hours old
The token must not have expired yet

Facebook:

curl -G "https://graph.facebook.com/v23.0/oauth/access_token" \  
-d "grant_type=fb_exchange_token" \  
-d "client_id={app_id}" \  
-d "client_secret={app_secret}" \  
-d "fb_exchange_token={long_lived_token}"

Instagram:

curl -G "https://graph.instagram.com/refresh_access_token" \  
-d "grant_type=ig_refresh_token" \  
-d "access_token={long_lived_token}"

Threads:

curl -G "https://graph.threads.net/refresh_access_token" \  
-d "grant_type=th_refresh_token" \  
-d "access_token={long_lived_token}"

💡 Pro tip: Set up a scheduled job to refresh tokens that are between 24 hours and 59 days old. If you miss the window, the user will need to re-authenticate from scratch.

Common Pitfalls

Stopping at the short-lived token — The #1 mistake. Your app will work for an hour in development and then break in production. Always exchange for long-lived.
Mixing up grant types — Facebook uses fb_exchange_token, Instagram uses ig_exchange_token for the initial exchange and ig_refresh_token for refresh. They look similar, but they’re not interchangeable.
Trying to refresh too early — If the long-lived token is less than 24 hours old, the refresh call will silently return the same token with the same expiry. It won’t error — it just won’t do anything.
Trying to refresh an expired token — Once expired, you can’t refresh it. The user must go through the full OAuth flow again.
Not storing the refresh token separately — For Meta, the long-lived token IS the refresh token. You exchange the existing long-lived token for a new long-lived token. This is different from platforms like Twitter or TikTok, which give you separate access_token and refresh_token values.
Forgetting about Page Access Tokens — If you’re posting to Facebook Pages, you also need a Page Access Token (covered in the next article). A user token alone won’t let you post to a page.
Not handling Instagram’s different base URLs — The initial token exchange goes to api.instagram.com, but the long-lived exchange and refresh go to graph.instagram.com. Different hosts for different operations.

TL;DR — The Full Flow

The complete Meta OAuth token lifecycle:

User clicks “Login” → Redirect to platform's authorization URL.
User grants permissions → Redirect back with ?code=... (expires in ~10 min)
POST /oauth/access_token → Short-lived token (~1 hour)
⭐ THE STEP EVERYONE MISSES: Exchange with fb_exchange_token (FB), ig_exchange_token (IG), or th_exchange_token (Threads) → Long-lived token (60 days)
Store token. Set up a refresh job.
Refresh every ~30 days (must be ≥24h old, must not be expired). FB: fb_exchange_token, IG: ig_refresh_token, Threads: th_refresh_token.

Quick Reference Table

Feature	FACEBOOK	INSTAGRAM	THREADS
Authorize URL	`www.facebook.com/v23.0/dialog/oauth`	`api.instagram.com/oauth/authorize`	`www.threads.com/oauth/authorize`
Auth code exchange	`POST graph.facebook.com/v23.0/oauth/access_token`	`POST api.instagram.com/oauth/access_token`	`POST graph.threads.net/oauth/access_token`
Short → Long exchange URL	`POST graph.facebook.com/v23.0/oauth/access_token`	`GET graph.instagram.com/access_token`	`GET graph.threads.net/access_token`
Short → Long exchange grant type	`fb_exchange_token`	`ig_exchange_token`	`th_exchange_token`
Refresh URL	`GET graph.facebook.com/v23.0/oauth/access_token`	`GET graph.instagram.com/refresh_access_token`	`GET graph.threads.net/refresh_access_token`
Refresh grant type	`fb_exchange_token`	`ig_refresh_token`	`th_refresh_token`
Token lifetime	60 days	60 days	60 days
Refresh window	24h after creation → before expiry	24h after creation → before expiry	24h after creation → before expiry

Dealing with the Meta API Headache?

If you've read this far, you know that Meta’s documentation is a moving target. Between versioned Graph API changes (like the jump to v23.0), inconsistent base URLs for Instagram, and the rigid 24-hour-to-60-day refresh window, token management becomes a high-maintenance sub-system in your codebase.

Beyond the tokens, getting your app through Meta's App Review and Business Verification is a multi-week process that requires screencasts, privacy policies, and strict data handling audits.

Consider a Unified API

If your goal is to build features rather than manage OAuth lifecycles and audit compliance, you might want to look at PostPulse for Developers.

We’ve built the PostPulse Social Media API specifically to solve these "last mile" integration problems. Instead of managing three different refresh flows for Facebook, Instagram, and Threads, you get:

Managed Token Refresh: We handle the 24h/60-day logic for you.
Unified Endpoints: One standard syntax for scheduling posts across 9+ platforms.
Bypass App Review: Use our pre-approved Meta, LinkedIn, and TikTok integrations to go live in hours, not weeks.

Save your engineering hours for your core product. Try the PostPulse API for free →