Meta Ads API: System User token setup

Let your agent do the setup

Copy this task into Claude Code or another agent with browser access. It will follow the guide and ask you when access or information is missing.

Read or select the prompt
Help me complete connect meta ads api to outloop using https://outloop.co/guides/connect-meta-ads-api-to-outloop.

Open that guide in your browser, read its full setup steps and linked official provider instructions, then perform the setup step by step using the tools available to you. If the guide cannot be opened, ask me for its contents before proceeding.

Identify the correct client Workspace, account, domain and environment before making changes. Inspect the current setup and preserve working settings. Ask me only for missing information, necessary authorization or access. Use an approved login-recovery tool when available. Otherwise, if a login such as GoDaddy, Google Admin or Microsoft 365 is required, ask me to sign in through the browser and resume after I finish. Never ask me to paste passwords, tokens, private keys or recovery codes into chat. Have me enter credentials directly into the authorized product form when needed.

Follow this guide’s actual provider-specific scopes, account identifiers, setup order and verification steps. Grant only the access required for the task. Keep secrets in the intended credential entry/storage path. Ask before creating paid resources, broadening permissions, rotating working credentials, publishing content or making destructive changes. Verify a bounded read-only operation in the intended client account before claiming the connection works. Do not launch campaigns, send messages or change production content merely to test authentication.

Continue through each supported step. If a human-only action or unavailable tool blocks progress, explain the exact action needed and resume when I complete it. Report what changed, what verification actually passed, and anything pending. Never claim completion based only on a success toast or a proposed command.

Last updated:

In short

To use the Meta Marketing API, create a System User in your Business Portfolio, assign the required app and ad accounts, then generate a token with the permissions your work needs.

This guide walks through the Meta setup first, then shows how to store the token in Outloop and restrict each workspace to its client accounts. Use the troubleshooting section if the token or account access fails.

All steps and troubleshooting

Your agency owns the Meta app

You create your own Meta Developer account and your own dedicated Meta app. Your agency controls the app, the business relationship, the permissions, the review status and the credential lifecycle. Outloop does not supply a shared developer account, a shared app, or a shared token, and it cannot shorten Business Verification, App Review or Advanced Access.

Outloop starts after Meta approves you. You connect your own approved credentials through the Outloop credential flow, Outloop binds the correct business, ad account, Page, catalog or Instagram resource to the correct client workspace, and every runtime request is audited and redacted without the raw credential ever reaching the agent.

Meta readiness: what always applies, what depends

Meta's requirements are not one flat checklist. Some apply to everyone; others depend on the permissions, access level, business type and actions your workflows genuinely need.

Always required

  • ✓A Meta Developer account.
  • ✓Your own app in the App Dashboard, with the app type and use case that match what you actually do.
  • ✓The app connected to your Business Portfolio.
  • ✓Approved access to the client assets your workflow touches — ad account, and the Page or Instagram business account where relevant.
  • ✓An active ad account for campaign and billing work.

Depends on your permissions, access level, business type and intended actions

  • ·Standard Access vs Advanced Access. Business apps get Standard Access automatically, which only lets you request permissions from people who hold a role on your app. Check whether Advanced Access and App Review are required for your permissions and whose assets your app accesses.
  • ·Business Verification. Required when your app requests advanced-level access and will be used to reach data belonging to businesses outside your own — which is the normal agency situation.
  • ·App Review. Required per individual permission and feature you request at advanced level. Meta expects at least one successful call using each of those permissions within the 30 days before you submit.
  • ·Live mode. Required before advanced-level permissions work for people without a role on your app.
  • ·A System User. The right choice for unattended agency automation and the flow this guide documents — but not universally mandatory. Which token type you need depends on the connection flow and assets involved.
  • ·Write permissions. Request ads_management or business_management only where the workflow genuinely writes or manages assets. ads_read is enough for a first proof.
  • ·Data Use Checkup. An annual re-certification once you hold permissions.

Business Verification is the long pole — start it first. Meta does not publish a guaranteed review time, and neither will we. Use the waiting period to finish asset assignment and design your first safe read. The submission itself is covered step by step in the Meta Marketing API App Review guide, and the wider model — what your agency owns versus where Outloop starts — is in professional API access readiness.

What you need before starting

Never paste access tokens, Authorization headers, or customer secrets into chat, screenshots, docs, .env files, project folders, agent prompts, or generated artifacts. The token's only destination is the local Outloop app in Step 7.

Step 1: Find your Business Portfolio ID

In Meta Business Settings (Meta Business Suite → Settings), open Business info. The Business Portfolio ID is shown below your portfolio name.

Meta Business Settings Business info page showing where the Business Portfolio ID appears, with identifiers redacted.
The Business Portfolio ID is optional, informational metadata in Outloop. It is not an access grant, and it does not replace the Meta ad account ID. Access is determined by the System User's assigned assets and the per-workspace ad account assignment in Step 9.

Step 2: Prepare the System User

Go to Business Settings → Users → System users. Select your dedicated System User, or create one for agent automation. Then confirm — under Assigned assets — that the ad accounts your workspaces will manage are assigned to this System User. A token can never reach an ad account its System User does not have.

Meta Business Settings System users page with a dedicated system user selected and the Generate token button highlighted.

Step 3: Click Generate token and select your own app

Click Generate token. In the app selector, choose your agency's own Meta app — the app you created and control.

Your app not in the list? Meta only shows apps connected to your business and to this System User. Open Business Settings → Accounts → Apps, confirm your app is added to the portfolio, and confirm the System User has access to it. Never select another organisation's app.

Step 4: Choose token expiration

Choose an expiration offered by Meta that meets your organization's policy. If Never is available, it means no scheduled expiration; the token can still stop working after revocation or changes to the app, permissions or assigned assets.

If that option is unavailable, use an offered expiration and record a renewal date. The screenshot shows an example, not a promise that every business sees the same choices. Follow the check-and-rotate sequence below.

Meta token expiration step showing the 60 days and Never options for a System User access token.

Step 5: Select permissions

Select the permissions the token will carry. Meta's documentation calls ads_read and ads_management the primary Marketing API permissions — the core set for reading and managing ads:

ads_read              # reporting and read-only access
ads_management        # campaign / ad set / ad / creative work
business_management   # only when workflows manage business portfolio assets

The remaining permissions in the approved set are optional — only needed for workflows that touch those assets: pages_manage_ads, pages_read_engagement, and pages_show_list for ads that run from a Facebook Page, catalog_management for catalog / commerce ads, and threads_business_basic for Threads workflows. Select what your client work actually uses.

Meta assign permissions step showing ads_management, ads_read, business_management and optional page, catalog, and Threads permissions selected before generating the token.

Step 6: Generate and copy the token

Click Generate token. Meta displays the token once. Copy it and go directly to the local Outloop app — do not paste it into chat, documentation, project files, .env files, screenshots, or agent prompts.

Meta Token created dialog with the token value redacted and the Copy button visible — Meta shows a System User access token only once.

Step 7: Add Meta Ads access in Outloop

In the Outloop Mac app, add access for Meta Ads and paste the System User access token once. (If a button in an older build still says "Add API Key", the value you are pasting is your System User access token — Outloop stores it the same way.) Then:

Outloop add Meta Ads access form with the optional Business Portfolio ID field, Graph API version, shared global scope, macOS Keychain Always Allow note, and the pasted token shown only as dots.

Outloop stores the token in the macOS Keychain and never shows it again. Agents never receive it — the credential is used on the wire, host-side, and results come back redacted.

Step 8: Find the Meta ad account ID

Back in Meta: Business Settings → Accounts → Ad accounts. Select the client ad account a workspace should manage and copy its numeric ID from the details panel. The account must already be accessible to your System User (Step 2) — assigning an ID in Outloop cannot grant access the token does not have.

Meta Business Settings Ad accounts page showing where the numeric Meta ad account ID appears in the account details panel, with account names redacted.

Step 9: Assign the ad account to the Outloop workspace

On the workspace's Meta Ads access row, open Meta ad account ID(s), enter the ID as digits only — comma-separate multiple IDs — and save. Outloop adds the act_ prefix internally.

Outloop workspace Meta Ads row with the Meta ad account ID field where digits-only account IDs are entered and saved.

This assignment is the tenant-safety boundary. Until at least one approved ad account is assigned, the workspace can prove identity (/me) but account-scoped calls stay blocked (CUSTOMER_RESOURCE_PIN_REQUIRED). Each workspace can manage different ad accounts under the same shared agency token.

Outloop Meta Ads access row showing Runtime verified with API bridge, Full API access, file and media upload enabled, destructive actions disabled, and the per-workspace Meta ad account ID field.

Step 10: Run the first proof

Click Copy workspace run prompt on the Meta Ads row and give it to the workspace's agent. The safe first proof is read-only:

GET /me                          # verify the System User identity
GET /act_<AD_ACCOUNT_ID>         # read the assigned ad account
GET /act_<AD_ACCOUNT_ID>/campaigns?limit=5   # bounded campaign list

Success criteria:

decision: allow
HTTP 200
secret_exposed: false
correct ad account only
audit entry exists
Outloop proof verdict showing allow decisions, HTTP 200, service meta_ads, secret_exposed false, and a bounded campaign list returned as all PAUSED, with account identifiers redacted.

A successful end state on the access row reads: Runtime verified · API bridge, Full API access, file / media upload enabled, your assigned Meta ad account ID(s), and secret_exposed: false on every audit entry.

What this connection enables

One Meta System User access token, stored once, working safely for every approved workspace:

One Meta System User access token
  → stored once locally in the macOS Keychain
  → shared securely through Outloop
  → assigned only to approved workspaces
  → one or more Meta ad account IDs pinned to each workspace
  → agents use approved Meta Marketing API capability
    without ever seeing the token

With Outloop's Full API access mode, agents operate across the Meta surface your agency has been approved for — not a read-only reporting slice. Where your app holds the required permissions and assets, that includes:

A safe read is the first proof, not the ceiling. Approved write operations run with workspace-to-resource pinning, action classification, redaction, a full audit trail, and human-approval gates. Delete and archive are separate destructive actions and stay disabled unless the operator explicitly enables them. What is actually available to you depends on the permissions, access level, App Review outcome and assets Meta has approved for your app.

The token itself is never handed to an agent. The credential is used on the wire, host-side; the agent receives a redacted, audited result. Each workspace is limited to the Meta ad account IDs assigned to it — see wrong-client access in agent loops.

How workspace restrictions work

Existing demo evidence: requests outside the workspace's assigned account are refused before a call reaches Meta.

Outloop Live Activity for demo workspace 018: allowed google_ads and meta_ads requests interleaved with three refused requests — two marked Deny with RESOURCE_ID_NOT_ALLOWED (one google_ads, one meta_ads) and one meta_ads request marked Deny with META_OBJECT_NOT_APPROVED.

Swipe sideways to read the log · open full size

Refused: these wrong-resource requests did not run

  • Deny · RESOURCE_ID_NOT_ALLOWED (google_ads and meta_ads) — the request named an account outside this Workspace’s approved resources; the requested action was refused
  • Deny · META_OBJECT_NOT_APPROVED (meta_ads) — a campaign, ad set or ad that does not belong to the approved ad account; the requested action is not sent to Meta
  • Approved requests in the same workspace keep executing around the refusals — Allow · OK

Real execution in an Outloop demo workspace (workspace 018), published in the September 26, 2026 proof pack — not a customer case study, and not evidence of ad spend, delivery or performance. Enforcement covers requests routed through Outloop. See the runtime access walkthrough for the recorded flow.

Optional: prove uploads and a PAUSED creative

Not required for the initial connection. When you want to confirm full capability on your own client account, run the same safe sequence used to runtime-verify this connector — it spends nothing and delivers nothing:

All of this works with destructive actions disabled — creating, updating, uploading, and pausing are normal operations.

Optional: enable delete and archive

Normal create / update / pause / upload operations do not require this. Enable destructive actions only when you intentionally want agents to permanently delete or archive Meta entities (campaigns, ad sets, ads, creatives) on the workspace's assigned accounts.

Outloop Meta Ads row showing destructive actions disabled by default with the optional Enable destructive actions button and a saved workspace ad account assignment.

Outloop asks for explicit confirmation and spells out the consequences before enabling:

Outloop confirmation dialog explaining that enabling destructive actions allows agents to delete or archive Meta entities, deletion is permanent, requests stay bounded to assigned accounts and audited.

What is verified vs what we don't claim

The one thing we still don't claim: delete and archive. They are not part of the verified default surface — they stay disabled until the operator explicitly enables destructive actions per workspace, and enabling them is an intentional decision, not a setup step.

Marketing API through Outloop vs the Meta ads MCP

Meta launched an official ads MCP server (mcp.facebook.com/ads), and it can create and edit campaigns, ad sets and ads. On 16 July 2026 Meta wrote that it is "opening up our ads MCP server to any developer with their own Meta app," and that it will be "gradually rolling out access to tools available to ad accounts through this integration method." Meta publishes no maturity label for it, so we state none. It is a real option for interactive ad work — but it is a different access model, and it is not connected or verified in this workspace.

API bridge: Live now Verified in this guide Audited Secret-safe Workspace-scoped
MCP: Official MCP exists Access rolling out Not connected here Not verified in this guide
For this workspace, the Meta Marketing API through Outloop is the only Meta Ads path that is live and verified right now.
Dimension Marketing API through OutloopMeta ads MCP (official)
Status here Runtime verified Read and write chain runtime-verified: allow, HTTP success, secret_exposed:false, audited. Not connected here Open to any developer with their own Meta app since 16 July 2026; Meta says tool access is still gradually rolling out.
Credential handling Token never seen System User access token stays in the macOS Keychain; used on the wire host-side. Meta-hosted auth You authenticate the AI client to Meta; access follows your Meta login/session.
Per-client scoping Workspace-pinned Each workspace is limited to its assigned Meta ad account IDs; wrong-client calls are blocked. Account-wide Scoped to what your Meta user can reach — no per-workspace ad account pinning.
Capabilities Full API access Reads, creation, updates, pause/resume, image and video upload; delete/archive off by default. Broad toolset Meta lists reporting, ad creation/management, catalog tools — not verified in this workspace.
Audit trail Local audit log Every request audited locally with decision, HTTP status, and secret_exposed:false. Platform-side Activity visible through Meta’s own surfaces; no local per-workspace audit.
Important: this comparison is intentionally conservative. The official Meta ads MCP may expose a broad toolset, but it is not connected in this workspace, so this guide does not mark MCP capabilities as verified. The Marketing API through the Outloop bridge is what is live and verified here.

Meta Marketing API errors and rate limits

Read the complete error, including its subcode and request ID, before changing permissions. Never include a token in a support ticket or screenshot.

Common Meta errors and next checks
CodeMeaningNext check
190Invalid OAuth tokenCheck token validity, app, expiration and permissions in Meta's token debugger. Do not assume every 190 means expiration.
200Permission errorCheck the permission, its access level and the System User's asset assignment.
100Invalid parameterCheck the endpoint, object ID, fields and current API version. Use the error message to identify the rejected input.
17User request limitReduce request frequency, inspect usage headers and retry with backoff.
80004 / 2446079Ads Management rate limitInspect X-Business-Use-Case-Usage and estimated_time_to_regain_access. Delay retries; the estimated recovery time is in minutes.

Rate limits depend on the API and business use case. Avoid a fixed requests-per-hour assumption. Cache repeated reads, bound reporting queries, request only needed fields and spread work across time. Retrying immediately can prolong throttling.

Checked 24 October 2026 · Meta error reference · Rate limiting

Check, rotate or revoke a System User token

  1. Inspect the token privately with Meta's Access Token Debugger. Check the app, validity, expiration and granted permissions. Do not share its input or an unredacted screenshot.
  2. Confirm the System User still has the app and required ad account assigned. A valid token alone does not grant every account.
  3. Generate a replacement under the correct app and store it in the Outloop access entry. Run a bounded read in every affected workspace.
  4. After the replacement works, revoke the old token and confirm it no longer works. If exposure is suspected, revoke immediately and restore access with a replacement.
  5. Record the owner and renewal date without recording the secret. Recheck access when people, apps or asset assignments change.

What the Marketing API works with

Campaigns contain ad sets, and ad sets contain ads. Ads reference creatives; a creative is not another level below the ad in that hierarchy. Insights queries return performance data at the supported account, campaign, ad set or ad level.

Start with account and campaign reads. Add reporting next. Creation, updates, media uploads and delivery changes require the relevant permissions and an explicit scope for the work. A successful read is not proof that every write operation is available.

Official Meta references

Common mistakes

The Outloop value

Meta gives the agency API access. Outloop makes that access tenant-safe:

One agency token may reach many ad accounts.
But each agent workspace only reaches the ad accounts assigned to it.

Related: AI agent API key management · Outloop for AI agencies · Meta Marketing API App Review guide · Google Ads API setup · WhatsApp Cloud API setup · AI for marketing agencies.

Outloop is available with setup guides and product support for agency teams. Outloop is an independent tool and is not affiliated with or endorsed by Meta. See the security model.

Summarize this setup guide with AI ChatGPTClaudePerplexity

Is this for you?

A good fit if…

  • You manage several clients’ Meta ad accounts through a Business portfolio.
  • You want agents to read or build only in the right ad account.
  • You can set up a Meta app and the permissions Meta requires.

You may not need Outloop if…

  • You manage one ad account and never share access.
  • You only need Meta reporting that an existing connector already delivers well.
  • You cannot complete Meta’s app and permission requirements for your agency.

Run Meta Ads agents without handing over tokens.

Outloop is available with setup guides and product support for AI agencies, operators, and dev shops.

Frequently Asked Questions

Meta Ads API + Outloop — FAQ