> For the complete documentation index, see [llms.txt](https://docs.omnata.com/omnata-product-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.omnata.com/omnata-product-documentation/omnata-sync-for-snowflake/apps/microsoft_ads.md).

# Microsoft Ads

## Authentication methods

### OAuth

The plugin has one connection method: **OAuth**. You bring your own Entra app registration and Microsoft Advertising Developer Token.

#### Prerequisites

Before you can connect you need three things on the Microsoft side:

1. **A Microsoft Advertising account** with a Super Admin user that you can authorise the connection with. The Microsoft user completing the OAuth flow must be both the user in the Azure portal and the Ads account(s) you intend to sync.
2. **A Microsoft Advertising Developer Token**. See Microsoft's [Get a Developer Token](https://learn.microsoft.com/en-us/advertising/guides/get-started?view=bingads-13#get-developer-token) guide.
3. **An Azure Entra app registration** configured for OAuth. 

#### 1. Register an app in Microsoft Entra

Follow Microsoft's [Authentication with OAuth — register your application](https://learn.microsoft.com/en-us/advertising/guides/authentication-oauth-register?view=bingads-13) guide to create the Entra app registration. From that page, you will need to enter in the Omnata UI:

* **Application (client) ID**
* **Directory (tenant) ID**
* **Client Secret** (created under **Certificates & secrets** on the app registration)
* **Microsoft Ads Developer Token**

#### 2. Add the redirect URI

On your Entra app registration, add a redirect URI under **Authentication → Add a platform → Web**. When you click to **Create a Connection** in Omnata, the Redirect URI will be constructed and displayed on the **Connectivity** step. 

#### 3. Confirm the OAuth scopes

The plugin requests the following Microsoft Entra scopes that should be added and consented in the app registration:

* Microsoft Graph > Delegated Permissions > `openid`
* Microsoft Graph > Delegated Permissions > `offline_access`
* APIs my organization uses > Microsoft Adverstising API Service > `msads.manage`

#### 4. Request a Developer Token in Microsoft Ads

The Developer Token can be request in **Microsoft Ads > Settings > Developer Settings**

Otherwise, follow Microsoft's [Get a Developer Token](https://learn.microsoft.com/en-us/advertising/guides/get-started?view=bingads-13#get-developer-token) guide.

#### 5. Complete the connection and OAuth flow in Omnata

In Omnata, che connection form requires the following:

| Field                    | Value                                                                      |
| ------------------------ | -------------------------------------------------------------------------- |
| Directory (tenant) ID:   | The Entra App (tenant) ID from your Entra app registration (Step 1).       |
| Application (client) ID: | The Entra App (client) ID from your Entra app registration (Step 1).       |
| Client Secret            | A client secret value from the Entra App. Stored as a secret in Snowflake. |
| Developer Token          | The Microsoft Ads Developer token from Step 4.                             |

Other values from the Entra App are not required. 

You'll then be redirected through Microsoft Entra to complete the OAuth authorisation. Sign in as the **same user** who has access to the Microsoft Advertising account(s) you intend to sync.

#### Using 'common' instead of Tenant ID

In some instances where user accounts between Microsoft Ads and Azure do not align, Microsoft recommends allowing authentication access to all Microsoft Accounts. \
To do this, go to the **Entra App > Authentication > Supported Accounts >** set to **"Any Entra ID Tenant + Personal Micosoft Accounts"**

 Then, replace the specific Tenant ID in the Omnata connection form with `common` . This will connect via a single public endpoint, instead of one for your specific tenant. 

## Inbound Syncs

The following streams are supported:

* accounts
* campaigns
* ad sets
* ads
* report\_campaign\_daily (basic campaign metrics at a daily granularity)

## Outbound Syncs

Currently there is no outbound sync functionality, but uploading offline conversions is coming soon!


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.omnata.com/omnata-product-documentation/omnata-sync-for-snowflake/apps/microsoft_ads.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.