> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markifact.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom Microsoft Ads App
> Connect Microsoft Ads through your own Azure app and developer token (white-label) by pasting your client ID, client secret, refresh token, and developer token.
Markifact supports two ways to connect Microsoft Ads: using the built-in **Markifact app** (Quick Connect) or connecting through your own **Azure app and Microsoft Advertising developer token** (Custom App). With a custom app, every request Markifact makes to the Microsoft Advertising API runs under your app and your developer token, so your clients never see Markifact in their account.
Custom app connections are available on the **Team** plan. See [White-label Connections](/core-concepts/white-label-connections) for the overview.
***
## Quick Connect vs Custom App
| Feature | Quick Connect | Custom App |
| :------------------------------------------ | :-------------------------- | :----------------------------------- |
| **Setup Time** | 1 minute | 20-30 minutes |
| **App and developer token the client sees** | Markifact's | Yours |
| **API rate limits** | Markifact's developer token | Your developer token |
| **White Label** | No | Yes |
| **Plan** | All plans | Team |
| **Best For** | Quick setup, testing | Agencies, strict client requirements |
***
## What You Need
Four values. Microsoft still requires a developer token on every API call, on top of the OAuth app that the user authorizes.
| Value | Where it comes from |
| :------------------ | :--------------------------------------------------------------------------------------------------------------------------------------- |
| **Client ID** | Your Azure app registration (Application (client) ID) |
| **Client Secret** | The same app registration, under Certificates & secrets |
| **Refresh Token** | Minted against that app with the `msads.manage` and `offline_access` scopes, by the Microsoft account that has access to the ad accounts |
| **Developer Token** | The [Microsoft Advertising developer portal](https://developers.ads.microsoft.com/Account), for the same Microsoft account |
Access tokens last one hour; Markifact refreshes them with your client ID and secret on every run. Refresh tokens stay valid as long as they are used at least every 90 days.
**Already have your own authorization flow?** If your systems already hold a refresh token issued by your Azure app with these scopes, skip to [Connect to Markifact](#connect-to-markifact).
***
## Setting Up Your Custom Microsoft Ads App
1. Open the [Azure portal](https://portal.azure.com/) and go to **Microsoft Entra ID** > **App registrations** > **New registration**
2. Enter your app name. This is the branding users see when they authorize
3. Under **Supported account types**, choose **Accounts in any organizational directory and personal Microsoft accounts**, so both work and personal Microsoft accounts can sign in to Microsoft Advertising
4. Under **Redirect URI**, choose **Web** and enter a URL you control (for example `https://www.youragency.com/microsoft-callback`). Microsoft appends the auth code to this URL after authorization; the page does not need to do anything
5. Click **Register** and copy the **Application (client) ID**
1. In the app registration, open **Certificates & secrets** > **New client secret**
2. Set a description and expiry, click **Add**, and copy the secret **Value** right away (it is shown only once)
Note the expiry: when the secret expires, Markifact can no longer refresh tokens until you create a new one and re-add the connection.
1. Open **API permissions** > **Add a permission** > **APIs my organization uses**
2. Search for **Microsoft Advertising** and add the delegated permission **msads.manage**
3. Also add **offline\_access**, **openid** and **email** under **Microsoft Graph** delegated permissions
1. Sign in to the [Microsoft Advertising developer portal](https://developers.ads.microsoft.com/Account) with the Microsoft account that has access to the ad accounts you want to manage
2. Request a token. A **single-user** token is issued immediately and works for that user; a **universal** token (any user) requires Microsoft's approval
3. Copy the developer token
1. Open the following URL in a browser, replacing the client ID and redirect URI:
```bash theme={"dark"}
https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=https%3A%2F%2Fwww.youragency.com%2Fmicrosoft-callback&response_mode=query&scope=openid%20email%20offline_access%20https%3A%2F%2Fads.microsoft.com%2Fmsads.manage&prompt=select_account
```
2. Sign in with the Microsoft account that has access to the ad accounts (the same account as the developer token) and accept the permissions
3. Microsoft redirects to your URL with `code=...` in the query string. Copy the value. Auth codes expire after a few minutes, so do the next step right away
Run this request, replacing the values (the redirect URI must match the one used above exactly):
```bash theme={"dark"}
curl -X POST "https://login.microsoftonline.com/common/oauth2/v2.0/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "code=THE_AUTH_CODE" \
-d "grant_type=authorization_code" \
-d "redirect_uri=https://www.youragency.com/microsoft-callback" \
-d "scope=openid email offline_access https://ads.microsoft.com/msads.manage"
```
The response contains `refresh_token`. Copy it.
> **Important:** Keep these values secure. Anyone holding the refresh token together with your client ID, secret and developer token can act on every ad account the user can reach.
1. In Markifact, go to the [Connections](https://app.markifact.com/connections) page
2. Click **Connect** on **Microsoft Ads**
3. Select the **Custom App (White-label)** tab
4. Enter a **Connection Name** (for example "Acme Agency Microsoft Ads")
5. Paste your **Client ID**, **Client Secret**, **Refresh Token**, and **Developer Token**
6. Click **Verify & Connect**
Markifact refreshes an access token with your app, then makes one Customer Management call with your developer token. Nothing is saved unless both succeed.
***
## Selecting Your Connection
Custom app connections appear under the name you chose, with a **Custom app** badge on the Connections page. Select them in Microsoft Ads nodes, agents, and MCP exactly like any other Microsoft Ads connection.
***
## Rotating or Replacing Credentials
Add the connection again with the **same connection name** and the new values (for example after a client secret expires). Markifact replaces the stored credentials in place, so workflows and agents bound to the connection keep working.
***
## Troubleshooting
Check the Application (client) ID and make sure you pasted the secret **Value**, not its ID. An expired client secret also fails this way; create a new one under **Certificates & secrets**.
The most common causes:
* The token was minted with a different client ID than the one you pasted
* The `offline_access` scope was missing, so no refresh token was issued
* The token lapsed (90 days without use) or the user revoked the app under their Microsoft account's **Privacy** > **Apps and services**
Run the authorization again and paste the new refresh token.
The developer token is wrong, or it belongs to a different Microsoft account than the one that minted the refresh token (a single-user developer token only works for its own user). Copy the token from the developer portal while signed in as the same account.
Sign in to Microsoft Advertising with that account at least once, or invite it to the ad accounts under **Settings** > **Users**, then authorize again.
***
## Summary
| Item | Where to Find | What It Looks Like |
| ------------------- | ------------------------------------------------- | -------------------------------------- |
| **Client ID** | Azure portal > App registrations > Overview | `00000000-0000-0000-0000-000000000000` |
| **Client Secret** | App registration > Certificates & secrets (Value) | `abc8Q~...` |
| **Refresh Token** | Response of the auth code exchange | `M.C5...` |
| **Developer Token** | developers.ads.microsoft.com > Account | `123ABC456DEF...` |
***
## Related
Overview of custom app connections across channels
Pull Microsoft Ads performance data