ENGINEERING PLAYBOOK

Meta Developer & Perpetual System User Token Walkthrough

The biggest hurdle in social automation is expiring tokens. Follow this battle-tested playbook to create permanent, never-expiring Meta Graph credentials in under 5 minutes.

STEP-BY-STEP SETUP GUIDE
1

Create a Meta Developer App

Log in to developers.facebook.com with your Facebook account. Navigate to My Apps > Create App.

  • Select Other > Click Next.
  • Choose Business as the App Type (Required for Instagram Graph API & System Users).
  • Enter your App Display Name (e.g., AgentDevi Social OS) and connect your Meta Business Portfolio.
2

Access Meta Business Manager System Users

Standard user tokens expire in 60 days. To obtain perpetual tokens, use a System User inside Meta Business Suite:

  • Navigate to Meta Business Settings (business.facebook.com/settings/system-users).
  • Under Users in the left sidebar, click System Users.
  • Click Add, name the user SocialOS-Bot, and assign the Admin role.
  • Click Add Assets > Assign your Facebook Page and Instagram Account with Full Control.
3

Generate Perpetual Token (Expiration: "Never")

Inside the System User details page:

  • Click Generate New Token.
  • Select your Meta App from Step 1.
  • Under Token Expiration, select Never.
Critical Note: Meta only displays this token once upon creation. Copy and store it immediately in your secure .env file.
4

Grant 5 Mandatory Permissions

During the token generation dialog, check the checkboxes for these 5 exact permissions:

☑ pages_show_list (Enumerate accessible Facebook Pages)
☑ pages_read_engagement (Verify feed engagement & read metrics)
☑ pages_manage_posts (Publish posts and delayed pinned comments)
☑ instagram_basic (Read Instagram profile and media container status)
☑ instagram_content_publish (Directly publish feed photos, carousels, reels)
5

Link Instagram Account to Facebook Page

Instagram Graph API requires your Instagram account to be a Professional (Business or Creator) account and linked to your Facebook Page:

  • In the Instagram Mobile App: Go to Settings > Account Type > Switch to Professional Account.
  • In Facebook Page Settings: Go to Linked Accounts > Instagram > Connect Account.
  • Obtain your Instagram Business Account ID via Meta Graph Explorer: GET /v22.0/{page-id}?fields=instagram_business_account.
6

Configure Meta Environment Credentials

Inject your Meta Graph API credentials into your .env file:

# Meta Graph API v26.0 (Never-Expiring System User Token)
META_APP_ID=your_meta_app_id
META_APP_SECRET=your_meta_app_secret
META_SYSTEM_USER_TOKEN=EAAG...your_perpetual_token...
7

Set Up Cloudflare Database (D1 Serverless SQL)

AgentDevi uses Cloudflare D1 — serverless relational SQLite replicated across Cloudflare's 280+ global edge locations:

  • Log in to dash.cloudflare.com > Navigate to Workers & Pages > D1 SQL Database.
  • Click Create database > Name it agentdevi-db.
  • Copy your Account ID and Database ID (UUID).
  • Click Console in D1 and execute cloudflare_d1_schema.sql, or use Wrangler CLI: 
    npx wrangler d1 execute agentdevi-db --file=cloudflare_d1_schema.sql
  • Add to your .env file: 
    DB_TYPE=cloudflare_d1
CLOUDFLARE_ACCOUNT_ID=your_account_id
CLOUDFLARE_D1_DATABASE_ID=your_database_uuid
CLOUDFLARE_API_TOKEN=your_cloudflare_api_token
8

Set Up Cloudflare Bucket (R2 Object Storage)

For high-resolution creatives, banners, and photo assets, AgentDevi utilizes Cloudflare R2 (Zero Egress Fees):

  • In Cloudflare Dashboard, navigate to R2 Object Storage.
  • Click Create bucket > Name it agentdevi-assets > Location: Automatic.
  • Click Manage R2 API Tokens > Create API token with Object Read & Write permissions.
  • Copy your Access Key ID and Secret Access Key into .env: 
    R2_ACCOUNT_ID=your_account_id
R2_BUCKET_NAME=agentdevi-assets
R2_ACCESS_KEY_ID=your_r2_access_key_id
R2_SECRET_ACCESS_KEY=your_r2_secret_access_key
R2_PUBLIC_URL=https://assets.agentdevi.online
INTERACTIVE TOKEN HEALTH CHECKER

Simulate Meta Debug Token Endpoint

Paste a sample token or click simulate to inspect how Social OS validates token validity, expiration status, and granted scopes.

TUTORIAL TROUBLESHOOTING
What if Meta shows error #100 "Unsupported post request"? +
This occurs when the Page ID or Instagram Account ID is incorrect, or if the System User has not been granted asset access to the target Facebook Page. Ensure you went to System Users > Add Assets > Pages > Grant Full Control.
Can I post to both Facebook Page and Instagram simultaneously? +
Yes! AgentDevi Social OS allows selecting dual dispatch. It first calls Facebook Page Feed endpoint, retrieves the object ID, and then triggers the Instagram Media Container creation and publish workflow.
How do I test my setup before publishing live? +
Use our built-in Dry-Run simulator on the Interactive Demo page. It tests your LLM generation prompts, formats payloads, and mocks the response before hitting live production servers.