Complete guide for setting up Instagram API authentication with n8n-nodes-instagram-integrations.
- Overview
- Prerequisites
- Authentication Methods
- Step-by-Step Setup
- OAuth2 Flow
- Access Token Method
- Troubleshooting
- Security Best Practices
- FAQs
This package supports OAuth2 authentication for seamless integration with Instagram's Messaging API. The authentication process connects your n8n workflows to Instagram Business Accounts through the Meta Graph API.
- ✅ Automatic Token Persistence - Long-lived tokens are stored in n8n's database and survive restarts
- ✅ Automatic Token Exchange - Short-lived OAuth tokens are automatically exchanged for 60-day tokens
- ✅ Automatic Token Refresh - Tokens are refreshed when near expiration (< 7 days remaining)
- ✅ No Manual Intervention - Everything is handled transparently by n8n's credential system
| Type | Recommended | Use Case | Auto-Refresh | Survives Restart |
|---|---|---|---|---|
| Instagram OAuth2 API | ✅ Yes | Production, long-term | Yes | ✅ Yes |
- Facebook Account - Personal or business account
- Facebook Page - Must be an admin/owner
- Instagram Business Account - Professional account linked to Facebook Page
- Meta Developer Account - Free registration at developers.facebook.com
Your Meta app needs these permissions:
- ✅
instagram_basic- Basic profile information - ✅
instagram_manage_messages- Send and receive messages - ✅
pages_manage_metadata- Subscribe to webhooks - ✅
pages_read_engagement- Read page engagement data
- n8n version 0.196.0+
- Node.js 18.15+ or 20.10+
- HTTPS domain (for OAuth2 callback and webhooks)
Advantages:
- ✅ Automatic token exchange (short-lived → 60-day long-lived)
- ✅ Automatic token refresh when near expiration
- ✅ Token persists through n8n/Docker restarts (v1.5.7+)
- ✅ Secure authorization flow
- ✅ No manual token management
- ✅ Best for production
How It Works (v1.5.7+):
- User clicks "Connect my account"
- Popup opens Meta login
- User authorizes permissions
- n8n receives short-lived access token (1 hour)
- First API call: Token is automatically exchanged for 60-day long-lived token
- Token is persisted to n8n's database (survives restarts)
- When token nears expiration (< 7 days): Automatically refreshed
- Workflow continues working indefinitely without manual intervention
Advantages:
- ⚡ Quick setup for testing
- 🔧 Full control over token lifecycle
- 🛠️ Useful for debugging
Disadvantages:
- ⏰ Manual token renewal required
- 🔄 No automatic refresh
Process:
- Generate token in Meta Developer Console
- Copy and paste into n8n credentials
- Instagram Account ID auto-discovered
- Manually refresh when expired
- Go to Meta for Developers
- Click Get Started (top right)
- Complete registration with your Facebook account
- Verify email if prompted
- Click My Apps → Create App
- Select use case:
- Business (recommended for most users)
- Or Consumer for personal projects
- Fill in app details:
App Name: My Instagram n8n Integration App Contact Email: your-email@example.com Business Account: (select or create) - Click Create App
- Complete security check if prompted
- In App Dashboard, scroll to Add Products
- Find Instagram → Click Set Up
- Instagram product added to left sidebar ✅
- Click Instagram → Basic Display
- Click Create New App
- Fill in:
Display Name: n8n Instagram Bot Valid OAuth Redirect URIs: https://your-n8n.com/oauth/callback Deauthorize Callback URL: https://your-n8n.com/oauth/deauth Data Deletion Request URL: https://your-n8n.com/oauth/delete - Click Save Changes
- Still in Basic Display tab
- Scroll to User Token Generator
- Click Add or Remove Instagram Accounts
- Login to Instagram (Business Account)
- Authorize the app
- Account appears in list ✅
- Go to Settings → Basic (left sidebar)
- Note your credentials:
App ID: 1234567890123456 App Secret: [Click Show] abc123def456... - Keep these secure! 🔒
- Go to Facebook Page Settings
- Click Instagram (left sidebar)
- Click Connect Account
- Login to Instagram Business Account
- Confirm connection
Option 1: Using Graph API Explorer (Quick)
- Go to Graph API Explorer
- Select your app from dropdown
- Click Generate Access Token
- Grant permissions:
- ✅ instagram_basic
- ✅ instagram_manage_messages
- ✅ pages_manage_metadata
- ✅ pages_read_engagement
- Copy the generated token (starts with
EAA...)
Option 2: Using Access Token Tool
- Go to Access Token Tool
- Find your Page
- Click Generate Token
- Select permissions
- Copy Page Access Token
Method 1: Auto-Discovery (Easiest)
The package automatically discovers your Instagram Business Account ID when you use the Instagram Access Token API credential type.
Method 2: Manual Lookup
- Go to Graph API Explorer
- Use your Page Access Token
- Make request:
GET /{page-id}?fields=instagram_business_account - Copy the
instagram_business_account.idvalue
Method 3: Using Facebook Business Manager
- Go to Business Settings
- Click Instagram Accounts
- Select your account
- ID shown in URL or account details
-
Open n8n
- Navigate to Credentials (left sidebar)
- Click + New Credential
-
Select Credential Type
- Search for "Instagram"
- Select Instagram OAuth2 API
-
Configure OAuth2
Credential Name: Instagram Bot Client ID: [Your App ID from Step 6] Client Secret: [Your App Secret from Step 6] OAuth Callback URL: (auto-filled by n8n) Copy this URL for Meta App settings -
Update Meta App Redirect URIs
- Go to Meta App → Instagram → Basic Display
- Add n8n's OAuth Callback URL to Valid OAuth Redirect URIs
- Save changes
-
Authorize in n8n
- Back in n8n, click Connect my account
- Popup opens → Login to Facebook
- Authorize permissions
- Popup closes → Credential saved ✅
-
Test Connection
- Click Test credential
- Should show: ✅ "Credential test successful"
-
Open n8n
- Navigate to Credentials
- Click + New Credential
-
Select Credential Type
- Search for "Instagram"
- Select Instagram Access Token API
-
Configure Token
Credential Name: Instagram Bot (Token) Access Token: [Your Page Access Token from Step 8] (Paste the entire EAA... token) Instagram Business Account ID: (Leave empty for auto-discovery) Webhook Verify Token: (Optional, for webhooks) my_secure_verify_token_2024 -
Save & Test
- Click Save
- Account ID automatically discovered ✅
- Click Test credential to verify
- Create new workflow in n8n
- Add Instagram Trigger node
- Select your credential
- Copy the Webhook URL shown
https://your-n8n.com/webhook/abc123-def456-ghi789
-
Go to Meta App Dashboard
-
Click Instagram → Configuration (or Messenger tab)
-
Scroll to Webhooks
-
Click Add Callback URL
-
Fill in Webhook Settings:
Callback URL: [Your n8n Webhook URL from Step 10] https://your-n8n.com/webhook/abc123-def456-ghi789 Verify Token: [Same token from credential setup] my_secure_verify_token_2024 -
Click Verify and Save
- Meta sends GET request to n8n
- n8n responds with challenge
- Status shows ✅ "Complete"
- In Webhooks section, click Add Subscriptions
- Select your Instagram Account
- Check these fields:
- ✅
messages - ✅
messaging_postbacks - ✅
messaging_optins
- ✅
- Click Save
- Send a message to your Instagram Business Account
- Check n8n workflow execution
- Should see incoming message data ✅
User clicks "Connect"
↓
n8n redirects to Meta login
↓
User authorizes permissions
↓
Meta redirects back to n8n
↓
n8n receives short-lived token (1 hour)
↓
First API request triggers preAuthentication:
↓
┌─────────────────────────────────────────────┐
│ Token Exchange (automatic) │
│ Short-lived token → 60-day long-lived │
│ Token persisted to n8n database │
└─────────────────────────────────────────────┘
↓
Workflow runs normally
↓
┌─────────────────────────────────────────────┐
│ Token Refresh (automatic, when < 7 days) │
│ Old token → New 60-day token │
│ Updated token persisted to database │
└─────────────────────────────────────────────┘
| Stage | Token Type | Validity | Action |
|---|---|---|---|
| OAuth | Short-lived | 1 hour | Received from Meta |
| Exchange | Long-lived | 60 days | Automatic on first API call |
| Active | Long-lived | 60 days | Persisted in n8n database |
| Near Expiry | Long-lived | < 7 days | Auto-refreshed |
| Refreshed | Long-lived | 60 days | New token persisted |
Important Notes:
- ✅ Tokens survive n8n restarts, Docker container restarts, and server reboots
- ✅ Refresh only happens if token is at least 24 hours old (Instagram API requirement)
- ✅ If refresh fails but token is still valid, the existing token continues to work
⚠️ If token fully expires (workflow not run for 60+ days), user must reconnect
{
"scope": "instagram_basic,instagram_manage_messages,pages_manage_metadata,pages_read_engagement"
}Note: As of v1.5.7, you don't need to manually manage tokens. The OAuth2 credential type handles all token exchange and refresh automatically. This section is kept for reference only.
Token Exchange (short-lived → long-lived):
GET https://graph.instagram.com/access_token
?grant_type=ig_exchange_token
&client_secret=YOUR_APP_SECRET
&access_token=SHORT_LIVED_TOKEN
Response:
{
"access_token": "IGQ...",
"token_type": "bearer",
"expires_in": 5183944
}Token Refresh (when < 7 days remaining):
GET https://graph.instagram.com/refresh_access_token
?grant_type=ig_refresh_token
&access_token=LONG_LIVED_TOKEN
Response:
{
"access_token": "IGQ...",
"token_type": "bearer",
"expires_in": 5183944
}All of this is handled automatically by the
preAuthenticationhook in the credential type. The refreshed token is persisted to n8n's database, ensuring it survives restarts.
Causes:
- Token expired (workflow not run for 60+ days)
- Token revoked by user in Instagram/Facebook settings
- Missing required permissions
- App removed from user's authorized apps
Solutions:
- Re-authorize credential in n8n:
- Go to Credentials → Instagram OAuth2 API
- Click "Connect my account" to re-authenticate
- The system will automatically get a new long-lived token
- Check token expiry in Access Token Debugger
- Verify all permissions are still granted
- Check if the Instagram account is still connected to the Facebook Page
Note (v1.5.7+): If you see this error after an n8n restart, it may indicate the token wasn't properly persisted. Try re-authenticating once to ensure the long-lived token is stored correctly.
Causes:
- Missing app permissions
- App not in live mode
- Business verification required
Solutions:
- Go to Meta App → Roles → Add your account as admin
- Request advanced permissions in App Review
- Complete Business Verification if required
Causes:
- Verify token mismatch
- n8n webhook not accessible
- Firewall blocking Meta
Solutions:
- Ensure verify token matches exactly (case-sensitive)
- Test webhook URL is publicly accessible
- Check HTTPS certificate is valid
- Whitelist Meta IP ranges in firewall
Causes:
- 24-hour messaging window expired
- User hasn't started conversation
- Account not eligible
Solutions:
- Wait for user to message first
- Use message tags for out-of-window messages
- Verify account is Instagram Business Account
- 🔒 Never commit credentials to version control
- 🔒 Use environment variables in production
- 🔒 Rotate tokens regularly (every 30 days)
- 🔒 Limit token permissions to minimum required
- 🔒 Monitor access logs for suspicious activity
- ✅ Always validate webhook signatures
- ✅ Use HTTPS for all endpoints
- ✅ Verify token is strong (20+ characters)
- ✅ Rate limit webhook endpoints
- ✅ Log failures for monitoring
n8n stores credentials encrypted:
- Credentials encrypted at rest
- Encryption key in environment variable
- Access restricted by user permissions
- Audit logs for credential access
A: Use OAuth2 for production (automatic refresh). Use Access Token for testing or when you need manual control.
A:
- Short-lived (from OAuth): 1 hour
- Long-lived (after exchange): 60 days
- With OAuth2 credential (v1.5.7+): Indefinitely, as long as workflow runs at least once every 60 days
A: Yes! As of v1.5.7, long-lived tokens are automatically persisted to n8n's database. They survive:
- n8n service restarts
- Docker container restarts
- Server reboots
- n8n updates
A: The token is automatically refreshed when:
- Token has less than 7 days remaining before expiration
- Token is at least 24 hours old (Instagram API requirement)
- An API request is made (triggers the refresh check)
A: No, you must use an Instagram Business Account or Instagram Creator Account connected to a Facebook Page.
A: For basic testing (your own account), no. For production (other users), you need to submit your app for App Review and get advanced permissions approved.
A: User IDs come from:
- Webhook events (when users message you)
- Graph API calls to conversations endpoint
- User interactions with your Instagram account
A: No, users must initiate conversation first. After that, you have a 24-hour window to respond. Use message tags for exceptions (e.g., updates, events).
A: 200 API calls per hour per user. Webhooks can receive unlimited events.
A: Use Meta's Graph API Explorer to test API calls. For webhooks, use tools like ngrok to test locally.
- 💬 Meta Developer Community
- 💬 n8n Community Forum
- 📧 Package Support: 9259samei@gmail.com
Authentication setup complete! 🎉 You're ready to build Instagram automation workflows in n8n.