> ## Documentation Index
> Fetch the complete documentation index at: https://nango.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Ads

## Overview

<CardGroup cols={3}>
  <Card title="Pre-built tooling" icon="screwdriver-wrench" href="#pre-built-tooling" />

  <Card title="Pre-built integrations" icon="square-check" href="#pre-built-integrations" />

  <Card title="Access requirements" icon="triangle-exclamation" href="#access-requirements" />

  <Card title="Setup guide" icon="rocket" href="#setup-guide" />

  <Card title="Useful links" icon="circle-info" href="#useful-links" />

  <Card title="API gotchas" icon="biohazard" href="#api-gotchas" />
</CardGroup>

## Pre-built tooling

<AccordionGroup>
  <Accordion title="✅ Authorization">
    | Tools                           | Status |
    | ------------------------------- | ------ |
    | Pre-built authorization (OAuth) | ✅      |
    | Credentials auto-refresh        | ✅      |
    | Auth parameters validation      | ✅      |
    | Pre-built authorization UI      | ✅      |
    | Custom authorization UI         | ✅      |
    | Expired credentials detection   | ✅      |
  </Accordion>

  <Accordion title="✅ Read & write data">
    | Tools                                     | Status                         |
    | ----------------------------------------- | ------------------------------ |
    | Pre-built integrations                    | 🚫 (time to contribute: \<48h) |
    | API unification                           | ✅                              |
    | 2-way sync                                | ✅                              |
    | Webhooks from Nango on data modifications | ✅                              |
    | Real-time webhooks from 3rd-party API     | 🚫 (time to contribute: \<48h) |
    | Proxy requests                            | ✅                              |
  </Accordion>

  <Accordion title="✅ Observability & data quality">
    | Tools                   | Status |
    | ----------------------- | ------ |
    | HTTP request logging    | ✅      |
    | End-to-end type safety  | ✅      |
    | Data runtime validation | ✅      |
    | OpenTelemetry export    | ✅      |
    | Slack alerts on errors  | ✅      |
    | Integration status API  | ✅      |
  </Accordion>

  <Accordion title="✅ Customization">
    | Tools                              | Status                         |
    | ---------------------------------- | ------------------------------ |
    | Create or customize use-cases      | ✅                              |
    | Pre-configured pagination          | 🚫 (time to contribute: \<48h) |
    | Pre-configured rate-limit handling | 🚫 (time to contribute: \<48h) |
    | Per-customer configurations        | ✅                              |
  </Accordion>
</AccordionGroup>

*No pre-built syncs or actions available yet.*

<Tip>Not seeing the integration you need? [Build your own](/guides/functions/functions-guide) independently.</Tip>

## Access requirements

| Pre-Requisites    | Status         | Comment                                                                                                                                           |
| ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Paid dev account  | ✅ Not required | Free, self-signup for a [Microsoft account](https://account.microsoft.com/account) and [Azure account](https://azure.microsoft.com/free).         |
| Paid test account | ✅ Not required | Free Microsoft account can be used for testing.                                                                                                   |
| Partnership       | ✅ Not required |                                                                                                                                                   |
| App review        | ⚠️ Conditional | Required only if you want to publish your app to the Microsoft commercial marketplace or if your app needs admin consent for certain permissions. |
| Security audit    | ✅ Not required |                                                                                                                                                   |

## Setup guide

<Steps>
  <Step title="Create a Microsoft account and Azure account">
    If you don't already have them, sign up for a [Microsoft account](https://account.microsoft.com/account) and an [Azure account](https://azure.microsoft.com/free).
  </Step>

  <Step title="Register an application in Microsoft Entra ID">
    1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least an Application Developer.
    2. If you have access to multiple tenants, use the Settings icon in the top menu to switch to the tenant in which you want to register the application.
    3. From the search bar at the top of the Azure portal, search for **App registrations** and select it. Then choose **New registration**. Or from your left navigation tab, navigate to **Applications** > **App registrations** then choose **New registration**.
    4. Enter a meaningful name for your application, for example "Nango Integration".
    5. Under **Supported account types**, select the appropriate option based on your needs:
       * **Accounts in any organizational directory** - For multitenant apps that you want users in any Microsoft Entra tenant to be able to use.
       * **Accounts in any organizational directory and personal Microsoft accounts** - For multitenant apps that support both organizational and personal Microsoft accounts.
    6. Leave the **Redirect URI** section blank for now; we'll configure it in a later step.
    7. Click **Register** to complete the app registration.
  </Step>

  <Step title="Note your application (client) ID">
    After registration, you'll be taken to the application's Overview page. Record the **Application (client) ID**, which uniquely identifies your application and is used in your application's code as part of validating security tokens.
  </Step>

  <Step title="Add a redirect URI">
    1. In the left sidebar, select **Authentication**.
    2. Under **Platform configurations**, select **Add a platform**.
    3. Select **Web** as the platform type.
    4. Enter `https://api.nango.dev/oauth/callback` as the Redirect URI.
    5. Under **Implicit grant and hybrid flows**, check the boxes for **Access tokens** and **ID tokens** if your application needs them.
    6. Under **Advanced settings**, set **Allow public client flows** to **No** for web applications.
    7. Click **Configure** to save your changes.
  </Step>

  <Step title="Create a client secret">
    1. In the left sidebar, select **Certificates & secrets**.
    2. Under **Client secrets**, click **New client secret**.
    3. Enter a description for the secret and select an expiration period (6 months, 12 months, 24 months, or custom).
    4. Click **Add**.
    5. **Important**: Copy the secret value immediately and store it securely. You won't be able to see it again after you leave this page.
  </Step>

  <Step title="Configure token settings (optional)">
    1. In the left sidebar, select **Token configuration**.
    2. Here you can configure optional claims to be included in the ID and access tokens issued to your application.
    3. Click **Add optional claim** if you need to include additional information in your tokens.
  </Step>

  <Step title="Configure app visibility (optional)">
    If you want users to see your app on their My Apps page:

    1. From the search bar at the top of the Azure portal, search for **Enterprise applications**, select it, and then choose your app.
    2. On the **Properties** page, set **Visible to users?** to **Yes**.
  </Step>

  <Step title="Next">
    Follow the [*Quickstart*](/getting-started/quickstart).
  </Step>
</Steps>

<Tip>Need help getting started? Get help in the [community](https://nango.dev/slack).</Tip>

## Useful links

| Topic     | Links                                                                                                                   |
| --------- | ----------------------------------------------------------------------------------------------------------------------- |
| General   | [Microsoft Entra Admin Center](https://entra.microsoft.com)                                                             |
|           | [Azure Portal](https://portal.azure.com)                                                                                |
|           | [Microsoft Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer)                                  |
| Developer | [Microsoft identity platform documentation](https://learn.microsoft.com/en-us/entra/identity-platform/)                 |
|           | [Microsoft Graph API Overview](https://learn.microsoft.com/en-us/graph/overview)                                        |
|           | [How to register an Application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app)     |
|           | [OAuth 2.0 Authorization Code Flow](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow) |
|           | [Microsoft Graph Permissions Reference](https://learn.microsoft.com/en-us/graph/permissions-reference)                  |
|           | [Microsoft Authentication Libraries (MSAL)](https://learn.microsoft.com/en-us/entra/identity-platform/msal-overview)    |
|           | [Microsoft Graph API Reference](https://learn.microsoft.com/en-us/graph/api/overview)                                   |
|           | [Microsoft Graph Throttling Guidance](https://learn.microsoft.com/en-us/graph/throttling)                               |
|           | [Redirect URI Best Practices](https://learn.microsoft.com/en-us/entra/identity-platform/reply-url)                      |

<Note>Contribute useful links by [editing this page](https://github.com/nangohq/nango/tree/master/docs/integrations/all/microsoft-ads.mdx)</Note>

## API gotchas

* The Microsoft Advertising API doesn't offer a REST API, which means certain Nango functionalities won't be accessible, including syncs, workflows, and proxy requests.
* To engage with the Microsoft Advertising API, developers must initially retrieve the access token utilizing the [backend API](/reference/api/connection/get). This token should then be utilized with [official client libraries](https://learn.microsoft.com/en-us/advertising/guides/client-libraries?view=bingads-13) or a [SOAP Client](https://learn.microsoft.com/en-us/advertising/guides/authentication-oauth-quick-start?view=bingads-13) for further interaction.

- Make sure you request the `offline_access` scope to get a refresh token and keep access with your integration.
- Microsoft offers a tool that allows you to construct and perform Graph API queries and see their response for any apps on which you have an admin, developer, or tester role. For more information you can check [Microsoft Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer).
- Please be aware that the Microsoft Graph API implements throttling to manage the volume of requests. For more information on handling throttling, refer to the [Microsoft Graph Throttling Guidance](https://learn.microsoft.com/en-us/graph/throttling).
- Microsoft Graph API has different versions (v1.0 and beta). The v1.0 endpoint is for production use, while the beta endpoint contains features that are still in preview.
- When requesting permissions that require admin consent, users without admin privileges will not be able to complete the OAuth flow unless an admin has pre-authorized the permissions.
- For multitenant applications, you may need to handle tenant-specific endpoints and permissions.
- You can set the [`.default` scope documentation](https://learn.microsoft.com/en-us/entra/identity-platform/scopes-oidc#default-when-the-user-gives-consent) to ensure the permissions remain the same as those granted at the organization level.
- The `.default` scope can't be combined with the scopes registered in the Azure portal. So either just use the `.default` scope or remove it to list out explicit parameters that are required. If you attempt to combine them you'll receive the following error

```
.default scope can't be combined with resource-specific scopes
```

* If you need a user to reauthenticate or accept updated scopes, you can force a prompt using the `authorization_params`. Use `prompt=login` to force the user to enter their credentials (bypassing single-sign on) or `prompt=consent` to trigger the OAuth consent dialog after sign-in, which asks the user to grant permissions to the app. For more details, see [Microsoft's OAuth 2.0 authorization documentation](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow#request-an-authorization-code).

```typescript theme={null}
const { data } = await nango.createConnectSession({
  [...],
  integrations_config_defaults: {
    "<provider-name>": {
      authorization_params: {
        "prompt": "consent" // or "login" depending on your needs
      }
    }
  }
});
```

<Note>Contribute API gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs/integrations/all/microsoft-ads.mdx)</Note>