Learn · Setup guides

Connect Meta Ads API to Outloop

Last updated: July 12, 2026

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 can run the normal supported Marketing API operations on their workspace's assigned ad accounts: reads and reporting; campaign, ad set, ad, and creative creation; normal updates; pause and resume; image upload; video upload; and creative asset use. Delete and archive are separate destructive actions and stay disabled unless the operator explicitly enables them.

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.

What you need before starting

• ✓An active Meta Business Portfolio.
• ✓A System User in that portfolio.
• ✓The required ad accounts assigned to that System User.
• ✓Access to the approved Outloop Ads Access app in your portfolio's app list. Meta requires the app and the System User to be connected to your business — during guided onboarding the app is shared with your portfolio (Business Settings → Accounts → Apps). If it doesn't appear in your token dialog, contact support@outloop.co before continuing.
• ✓The Outloop Mac app installed.
• ✓A workspace already connected in Outloop.

If your team runs its own Meta app instead, Marketing API access is governed by the Meta Marketing API Access Tier (Limited access by default; Full access after App Review) — that separate path is covered in the Meta Marketing API App Review guide. This guide documents the approved-app flow.

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.

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.

Step 3: Click Generate token and select Outloop Ads Access

Click Generate token. In the app selector, choose Outloop Ads Access — the approved app you were given access to during onboarding. You do not need to create your own Meta app for this flow.

Step 4: Choose token expiration

For uninterrupted agency workflows, you may choose Never for a dedicated System User with tightly limited business assets. Choose a shorter expiration when required by your organization's security policy. Tokens can be revoked and rotated later at any time from the same System users screen.

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.

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.

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:

• ✓Business Portfolio ID — optional and informational only (from Step 1).
• ✓Store the access as Shared / global — one agency token, assigned per workspace afterwards.
• ✓When macOS asks for Keychain access during the first proof, enter your Mac login password and click Always Allow so proofs don't re-prompt.

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.

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.

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.

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

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.

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:

• →Upload an image to the assigned ad account.
• →Upload a video and wait for Meta's asynchronous video processing to finish.
• →Create a clearly named test creative or ad in PAUSED status.
• →Confirm no delivery and no spend, then clean up manually in Ads Manager if you wish.

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 asks for explicit confirmation and spells out the consequences before enabling:

• →Deletion may be permanent — treat it accordingly.
• →Access stays limited to the workspace's assigned ad accounts.
• →Every request is still audited, and you can disable destructive actions again at any time.

What is verified vs what we don't claim

• Verified Read access through Outloop: identity (GET /me), the assigned ad account, and a bounded campaign list returned HTTP 200 with decision allow, audit entries, and secret_exposed: false — shown in Step 10.
• Verified Per-workspace scoping: account-scoped calls are blocked (CUSTOMER_RESOURCE_PIN_REQUIRED) until a Meta ad account ID is assigned to the workspace.
• Verified Write operations — campaign / ad set / ad / creative creation, updates, pause and resume, image upload (POST /act_<id>/adimages), video upload (POST /act_<id>/advideos) with asynchronous processing, and video thumbnails: runtime-verified through Outloop with HTTP success, decision allow, audit entries, and secret_exposed: false — using clearly named PAUSED test entities with no delivery and no spend.
• Disabled by default Delete / archive: blocked until the operator explicitly enables destructive actions for the workspace.

Marketing API through Outloop vs the Meta ads MCP

Meta launched an official ads MCP server (mcp.facebook.com/ads) in open beta in April 2026, alongside an ads CLI. 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.

Common mistakes

• ✕Pasting the System User access token into chat, a prompt, or .env — its only destination is the local Outloop app.
• ✕Entering the Business Portfolio ID where the Meta ad account ID belongs — they are different identifiers with different jobs.
• ✕Entering act_1234567890 in the workspace assignment — enter digits only; Outloop adds the prefix.
• ✕Enabling destructive actions "to make it work" — normal reads, creates, updates, pauses, and uploads never need it.
• ✕Assigning every workspace the same ad account list — the per-workspace assignment is what keeps clients separated.
• ✕Expecting an assigned ID to grant access the System User doesn't have — assets are granted in Meta Business Settings first.
• ✕Publishing screenshots with token values or client account IDs.

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.

Outloop is available with guided onboarding for agency teams. Outloop is an independent tool and is not affiliated with or endorsed by Meta. See the security model.