Connect your Instagram
test account.
Follow these steps for one Business or Creator account you own or manage. At the end, you’ll authorize it from the POC and see the data returned by Instagram.
For this test: Instagram Login, your own professional account, and three data permissions. A Facebook Page is not required. App Review is for access beyond eligible accounts added to your app.
Prepare your Instagram account
- Sign in to the Instagram account you want to fetch.
- Confirm it is a Business or Creator account. A Professional dashboard on your profile is a useful indicator.
- If it is personal, open your profile menu → Settings and activity → Account type and tools → Switch to professional account. Choose Creator or Business and finish the setup. Instagram’s menu labels can vary.
Check: the intended account is professional and public. Keep its Instagram username and login available.
Create the Meta app
Open Meta’s app creation page ↗. Sign in with your Meta developer account; complete developer registration if asked. If you already started, continue from the screen you’re on.
| Screen | What to select or enter |
|---|---|
| App details | Name: FameHire Instagram POC. Enter your contact email. Click Next. |
| Use cases | Select only Manage messaging & content on Instagram (Instagram icon), then Next. |
| Business | For this test, select I don’t want to connect a business portfolio yet, if offered, then Next. If you already have a suitable portfolio, you can select it. If Meta requires one for your account, follow that requirement. |
| Requirements | Review the listed requirements and click Next. You are setting up an own-account test; you do not need to submit an App Review application at this point. |
| Overview | Check the selected use case and click Go to dashboard to finish creation. |
The broad use-case name includes messaging and publishing, but our POC only requests access to profile data, insights, and comments.
Check: your app dashboard lists the Instagram use case. You do not need to add the Instagram product a second time.
Choose Instagram Login and permissions
- In the app dashboard, locate Manage messaging & content on Instagram and click Customize. You can also reach it through Use cases.
- In its left menu, select API setup with Instagram Login. This is the setup the POC implements. Meta currently allows one Instagram login setup per app.
- If shown, click Add all required permissions to initialize this setup.
- Open Permissions and features within this use case. Add the three permissions below if they are not already present.
| Permission | Data it enables |
|---|---|
instagram_business_basic | Profile details and media. |
instagram_business_manage_insights | Account and media statistics. |
instagram_business_manage_comments | Comments and replies. The POC only reads them. |
If messaging permissions appear automatically: Meta’s setup can add instagram_business_manage_messages by default. Leave any required, non-removable entries alone. Permissions present in Meta’s dashboard and permissions requested at login are different: the POC requests only the three above.
Check: you chose Instagram Login and all three permissions are listed. Standard Access is the path for eligible own/managed accounts added to the app; Advanced Access/App Review is for other creators.
Add your professional test account
- Return to API setup with Instagram Login.
- In Generate access tokens, click Add account.
- Click Continue and sign in to the professional Instagram account from step 1 in the popup.
- Complete the prompts, then click Save and Got it when shown.
- Check that the correct Instagram username now appears in the account list.
You are adding an account that is allowed to test the app. You do not need to copy or paste a generated access token. The POC obtains its own token when you click Connect Instagram later.
If Meta reports an insufficient developer role
Check App roles → Roles. If you add an Instagram tester there, sign in to that Instagram account and accept the pending invitation under Apps and websites → Tester invites (the location can vary). Return to Meta and retry Add account. A pending invitation is not an accepted tester role.
Check: the intended professional account is listed in API setup. Use this same account for the first POC login.
Get the POC’s HTTPS address
Terminal 1 — run the POC. If it is already running on port 3001, keep that process running and skip this command.
cd /Users/karolek/FameHireV2/pocs/famehire-pocs pnpm install pnpm dev --port 3001
Terminal 2 — start the HTTPS tunnel. ngrok is installed on this machine. If you have not connected it to an ngrok account, follow its account setup instructions ↗ first, then run:
ngrok http 127.0.0.1:3001 --inspect=false
The flag disables ngrok’s local request inspector so it does not capture profile responses or callback codes there. It does not configure ngrok’s cloud retention.
- Find the Forwarding line in ngrok.
- Copy the https://… address on that line. This is your app base URL. Keep both terminals running.
- Open that HTTPS address in your browser and confirm the FameHire POC loads.
Check: the POC loads over HTTPS. Use your actual forwarding hostname wherever the examples below say YOUR-HOST.
Set the callback and find the credentials
- In API setup with Instagram Login, find Set up Instagram business login and click Set up.
- In Redirect URL, enter your app base URL followed by
/api/auth/instagram/callback:
https://YOUR-HOST/api/auth/instagram/callback
- Click Save. Open Business login settings and verify the saved OAuth redirect URI matches exactly, including HTTPS and no trailing slash.
- Find Instagram app ID and Instagram app secret on the API setup page. Meta also documents these under Business login settings. Keep them ready for step 7.
| Value you need | Where it comes from |
|---|---|
| Instagram App ID | The credential explicitly labelled Instagram app ID in this Instagram setup. |
| Instagram App Secret | The matching Instagram app secret. Reveal it in Meta when you are ready to enter it locally. |
| Redirect URI | The full HTTPS callback you just saved, including /api/auth/instagram/callback. |
Use the Instagram credentials; the parent Meta app’s ID/secret from general App settings are not interchangeable. Keep the secret in your local environment file, not in chat.
What about webhooks, deletion URLs, and the Embed URL?
- Configure webhooks: skip it for this POC. Data is fetched on demand. An OAuth Redirect URL is not a webhook Callback URL; no Verify token is needed.
- Embed URL: no copy/paste is needed. The POC already builds the authorization URL with its three permissions.
- Privacy policy URL: the POC has
https://YOUR-HOST/privacy, a development data-handling notice. - Data deletion instructions URL: use
https://YOUR-HOST/data-deletiononly if Meta offers an instructions-URL option. - Deauthorization callback URL / Data deletion request callback: the POC has no handlers for these. Do not put the OAuth callback or instructions page in these fields. Leave optional callback fields empty for the local test. If Meta requires one to save, that is an additional implementation requirement; share the field label/error so it can be handled correctly.
Check: the login redirect is saved and you have the two Instagram credentials. A manually generated user token is not one of the required values.
Configure the POC
In the project folder, create .env.local from the example only if it does not already exist. This command keeps an existing file:
cd /Users/karolek/FameHireV2/pocs/famehire-pocs cp -n .env.example .env.local
Open .env.local in your editor. Fill in these five lines, replacing the placeholder values:
INSTAGRAM_APP_ID=YOUR_INSTAGRAM_APP_ID INSTAGRAM_APP_SECRET=YOUR_INSTAGRAM_APP_SECRET INSTAGRAM_REDIRECT_URI=https://YOUR-HOST/api/auth/instagram/callback INSTAGRAM_API_VERSION=v26.0 SESSION_ENCRYPTION_KEY=YOUR_64_HEX_CHARACTER_KEY
Generate the encryption key once with openssl rand -hex 32. Paste the 64-character result directly into your configuration, not chat or source control. Keep it identical across instances of this environment and use different keys for different environments.
On Vercel: skip the local tunnel. Add all five variables in Project → Settings → Environment Variables for the deployed environment. Use https://famehire-pocs.vercel.app/api/auth/instagram/callback as the production redirect, with the identical URL in Meta. Redeploy after saving variables, open the production domain, and reconnect. Old session cookies cannot be reused.
- Save the file. The redirect URI must be identical to the one saved in Meta.
- In Terminal 1, stop the POC with Ctrl+C, then run
pnpm dev --port 3001again. Keep ngrok running in Terminal 2. - Reload the POC through the HTTPS forwarding address.
The file is Git-ignored and holds app configuration. Fetched profile data and user access tokens are not saved there.
Check: Connect Instagram is enabled. This means the required settings are present and correctly shaped; the real login checks whether Meta accepts them.
Connect and check the data
- Open your HTTPS app base URL from step 5. Start login there so the session cookie and callback share the same host.
- Click Connect Instagram. Sign in to the same professional account added in step 4 and grant the requested access.
- After returning to the POC, check that your username appears. Overview loads profile and account metrics.
- Open Audience, Posts & reels, and Stories to fetch those sections.
- Open a post’s Fetch insights & comments. Use Load more for more results and Fetch replies on a comment.
- When finished, select Disconnect & clear.
Success: your account details and available data appear. Empty insights can reflect Meta’s audience/activity thresholds; expand availability notices to distinguish that from a permission error.
Encrypted session cookies work across Vercel instances and survive restarts with the same encryption key. Sessions expire after 55 minutes. Disconnect clears this browser’s cookies; copied cookies remain valid until expiry or key/token revocation. If your tunnel hostname changes, update the redirect in both Meta and .env.local, restart the POC, and connect again.
If you get stuck
| What you see | What to check |
|---|---|
| Connect button disabled | Expand Configuration still needed on the home page. Fill those settings in .env.local and restart the POC. |
| Invalid platform app / client ID | Use the Instagram product ID and matching secret from step 6. |
| Redirect URI mismatch | Compare the entire URL in Meta and .env.local: HTTPS, host, path, and trailing slash. |
| Insufficient developer role | Confirm the account is listed in API setup and any tester invitation has been accepted. |
| State error or missing session | Start again on the HTTPS app address in the same browser. Keep the server and tunnel running through login. |
| Insights or comments permission denied | Check the corresponding permission in step 3, then disconnect and reconnect to grant it. |
| No audience metrics, but profile loads | Some metrics need at least 100 followers or sufficient engagement. Data can also be delayed. Check the API notice; missing data is not zero. |
| Meta requires a deletion/deauthorization callback | See step 6. These callbacks are not implemented; an informational page cannot substitute for them. |
Later: connect creators who are not app testers
For accounts beyond the eligible ones you own/manage and have added to the app, complete Meta’s required business/tech-provider verification, obtain Advanced Access through App Review, and publish as required. The use-case workflow provides Review → Testing, Review → Verification, and Review → App Review. Complete the requirements Meta shows for your app.
The current privacy/deletion pages are development notices and need operator details before public use. Authentication is stored in encrypted HttpOnly session cookies; fetched profile data is never stored there. These public-launch steps are separate from the test above.
Verification notes and official sources
Checked on 4 October 2026 against Meta’s current app-creation and Instagram use-case guides, the supplied Use cases screenshot, and this POC’s configuration and OAuth code. The older Instagram-specific creation article still says “Other → Business”; it does not match the newer flow shown here.
- Meta: current app creation screens and business choices
- Meta: customize the Instagram use case, permissions, and test accounts
- Meta: Instagram credentials, redirect matching, and access levels
- ngrok: account setup and HTTPS forwarding
The account-specific screens after app creation have not been inspected in your logged-in dashboard. Where Meta makes a field mandatory for your app, that requirement takes precedence over the optional paths above. Live OAuth still needs your credentials and authorization.