Microsoft Ads

OAuthAdvertisingOrg connection

Org-level connection

Microsoft Ads is connected once at the org level by an admin. The credential is shared across all groups that have been granted access — individual team members don't need to connect their own accounts.

How to connect

Click "Connect with OAuth" below and sign in with the Microsoft account that has access to your Microsoft Advertising accounts. You'll be redirected to Microsoft to approve the connection.

After connecting, you'll be asked for three values:

- Developer Token — the partner-level entitlement key from Microsoft Advertising → Account settings → Developer settings. Sent as the DeveloperToken header on every API call.

- Customer ID — the identifier of the manager account (customer) you operate from.

- Account ID — the identifier of the ad account whose data you want On Belay to read.

Note: Microsoft Advertising standardizes on the REST v13 API. Find your Customer/Account IDs at https://learn.microsoft.com/en-us/advertising/guides/get-started#get-ids.

Ready to connect?

Permissions (scopes)

These are the data scopes On Belay can be granted for Microsoft Ads. Your org admin controls which scopes are enabled per group.

Scope	Description	Access
`https://ads.microsoft.com/msads.manage`	Manage Microsoft Advertising accounts (campaigns, reports)	Read / Write
`offline_access`	Maintain access (refresh token)	Read only

Troubleshooting

"redirect_uri_mismatch" error during OAuth

Your OAuth app's authorized redirect URIs don't include the On Belay callback URL. Add https://app.onbelay.ai/api/oauth-callback/microsoft_ads to the allowed redirect URIs in your OAuth app settings.

"invalid_scope" error

The API or scope isn't enabled in your cloud project. For Google integrations, make sure the relevant API (e.g. Google Ads API, Search Console API) is enabled in Google Cloud Console for your project.

Connected but Claude can't access data

Check that your group has been granted access to this integration in On Belay → Groups → [your group] → Integrations. Also verify the specific scopes your group is permitted to use match what your query requires.

Still stuck? We're happy to help.

Contact support →