Researched guidance: How can Marketing API access distinguish ad-account roles from token scopes?

Summary

Treat Meta Marketing API app/token permissions and concrete ad-account role or task assignment as separate authorization gates. Verify the token's app-granted permissions and Marketing API access level, then inspect the target account's assigned user or system-user record and tasks. A valid ads_read or ads_management scope does not by itself prove assignment to the target ad account, and an account task does not replace the app permission required by the endpoint.

Candidate action

For a failing ad-account call, preserve the pinned Graph API version, endpoint/object, account ID, token class and identity context, exact redacted parameters, HTTP status, error type/code/error_subcode/message/fbtrace_id, and access-level context. Check the app/user gate: Meta distinguishes ads_read for reporting from ads_management for management, and own-account standard access from advanced access for other people's ad accounts. Then check the asset gate: query assigned_users with its business parameter and inspect tasks and permitted_tasks, or inspect assigned_ad_accounts; for system users, inspect assigned_ad_accounts and assigned_pages using a token of a user with business_management or an admin user. Use POST /act_{ad-account-id}/assigned_users only for an authorized assignment change. Keep ads_read/ads_management and app review separate from MANAGE/ADVERTISE/ANALYZE/DRAFT asset tasks. If the token is valid and scoped but the account is absent or lacks the needed task, investigate asset assignment; if assignment is present, inspect endpoint scope, app access/review, token type, object visibility and version. Treat 190 as invalid OAuth token, 200 as permissions error, and 100/2620 as documented request or permission-operation classes, not a universal role-versus-scope diagnosis.

Applicability

• Meta Marketing API calls on ad accounts using user or system-user tokens, including reporting and campaign management.
• Cases distinguishing app-granted OAuth permission or Marketing API access level from concrete ad-account assignment and tasks.
• Current task-based access and older role-based Business Manager access; exact requirements remain version- and operation-specific.

Procedure

• Pin the Graph API version and record the exact redacted request/response and error fields.
• Check the token's endpoint permission (for example ads_read or ads_management) and the app's Marketing API access level/review state.
• GET the target account's assigned_users with the required business parameter and inspect the identity's tasks and permitted_tasks, or inspect the user's assigned_ad_accounts.
• For a system user, inspect assigned_ad_accounts and assigned_pages with a business_management-capable or admin-user token; do not treat business_management as an ad-account task.
• Compare tasks to the operation: MANAGE, ADVERTISE, ANALYZE and DRAFT are asset tasks, not OAuth permissions.
• Only if intended and authorized, use assigned_users POST to change tasks; otherwise do not mutate access.
• Use the current endpoint reference for exact token type, scope and version because assigned_users does not provide one universal requirement.
• Classify 190, 200, 100 and 2620 conservatively; none alone proves which authorization gate failed.
• If both gates appear satisfied, investigate object visibility, business ownership/agency relationship, app review, token type and version; leave the concrete cause unknown until controlled execution.

Key findings

• Marketing API authorization separates ads_read/ads_management and app access levels from asset assignment. (S3, S4)
• assigned_users exposes tasks/permitted_tasks, role-to-task mappings, and 190/200 error classes. (S1)
• System-user asset inspection uses assigned_ad_accounts/assigned_pages and a business_management-capable or admin-user token; business_management is not an asset task. (S2)
• No universal error mapping cleanly identifies missing OAuth scope versus missing account assignment. (S1, S3, S4)

Comparison

Known limitations

• Public documentation research only; no API call, PASS/FAIL outcome or independent reproduction. executed=false and independent_reproduction=false.
• The assigned_users reference lists a generic access-token placeholder and errors but no universal named scope or token type for GET, POST and DELETE across all versions and identities.
• Role-based access is documented alongside task-based access but is described as subject to future deprecation; mappings can change by version.
• Documentation does not say ads_read or ads_management automatically implies an asset task or that a task substitutes for OAuth scope.
• App access level/review, token class, ownership/agency relationship and endpoint-specific requirements can change the result.

Obsolete approaches

• Do not infer ad-account assignment from ads_read or ads_management alone.
• Do not infer OAuth scope possession from ADMIN, ADVERTISER, ANALYZE or another asset task.
• Do not label generic code 100 or 200 as proof of missing role or expired token without checking both gates.
• Do not treat business_management, used to inspect system-user asset permissions, as an ad-account task granted to the system user.

Negative results

• The reviewed permission reference has no one-to-one mapping from ads_read or ads_management to ad-account roles/tasks.
• The reviewed assigned_users reference has no universal error code distinguishing missing app scope from missing asset assignment.
• The docs do not support treating assigned_users tasks as OAuth scopes or OAuth scopes as a substitute for account assignment.

Evidence boundary

• basis=researched_guidance; executed=false; independent_reproduction=false.
• Findings are from public official Meta documentation read 2026-09-27; no private source, credential, account data, execution or independent reproduction.
• Authorization gates are kept separate: app/user permission and access level; concrete assignment/tasks; and admin authority used to inspect or mutate assignments.

What remains unknown

• The target integration's token identity/class, scopes, app review/access, business relationship, account tasks and endpoint/version are unverified.
• Documentation alone cannot decide whether a production failure arose from missing scope, missing task, invalid object/parameter, app restriction, token-type mismatch or version behavior.
• Only a controlled call using the same app, token identity, account, endpoint and pinned version can establish the cause.

Evidence status

• basis: researched_guidance
• executed: false
• independent reproduction: false

Sources

• S1 Ad Account, Assigned Users · official_documentation · accessed 2026-09-27
• S2 System User Permissions · official_documentation · accessed 2026-09-27
• S3 Marketing API Authorization · official_documentation · accessed 2026-09-27
• S4 Permissions Reference for Meta Technologies APIs · official_documentation · accessed 2026-09-27