How to Get Your Microsoft Advertising API Key
May 29, 2026
There is no single Microsoft Advertising API key. Access requires three things together: a Developer Token (the partner-level entitlement key), OAuth 2.0 credentials from a Microsoft Entra ID app registration (client ID + secret), and a user authorization flow that produces access and refresh tokens for a specific Microsoft Advertising user.
There's also a decision to make in 2026 that no other ad platform forces this year: which API to build against. Microsoft Advertising is mid-migration from its legacy SOAP API (Bing Ads API v13) to a newer REST API. SOAP enters feature freeze on October 1, 2026 — no new features after that date — and is fully decommissioned on January 31, 2027. For any new integration, target the REST API. SOAP is for maintaining existing systems through the transition only.
This guide covers the 2026 process: creating your Microsoft Entra ID app registration, requesting a Developer Token from the Microsoft Advertising Developer Portal, running the OAuth user-authorization flow, and avoiding the most common auth failures.
Key takeaways
- Microsoft Advertising requires three credentials together: Developer Token, OAuth client ID/secret, and user access/refresh tokens. None alone is sufficient.
- For new integrations in 2026, target the REST API. SOAP feature freeze is October 1, 2026; full shutdown is January 31, 2027.
- The Developer Token is partner-level entitlement — it identifies your integration, not the user. For first-party use, it's typically issued instantly to Super Admins through the Developer Portal.
- OAuth runs through the Microsoft identity platform (login.microsoftonline.com) — the docs may use the older Azure AD terminology or the newer Microsoft Entra ID branding. They refer to the same system.
- Delegated user OAuth is the only supported flow. Microsoft Advertising does not support service-principal / app-only OAuth, unlike many other Microsoft APIs.
- The scope is
https://ads.microsoft.com/ads.manageplusoffline_accessfor refresh tokens. - Microsoft Advertising offers a real separate sandbox environment — distinct accounts, distinct developer tokens, distinct endpoints. The OAuth mechanics are the same; the data is fully isolated.
Before you start
You'll need:
- A Microsoft Advertising account at
ads.microsoft.comwith Super Admin permissions (required to request the Developer Token) - A Microsoft Entra ID tenant (your Azure / Entra portal at
entra.microsoft.comorportal.azure.com) - An understanding of which Microsoft Advertising Customers and Accounts your integration needs to access — Microsoft's hierarchy is Customer → Account → Campaigns / Ad Groups / Ads
- For SaaS integrations: a backend that can store per-tenant CustomerId and AccountId values, plus refresh tokens
If your Microsoft Advertising account predates the rebrand and still says "Bing Ads" anywhere in the UI, that's normal — Microsoft hasn't fully scrubbed the old naming from every surface even years after the rebrand.
Step-by-step: creating Microsoft Advertising API credentials in 2026
1. Request your Developer Token
Sign in to the Microsoft Advertising Developer Portal at developers.ads.microsoft.com with the Super Admin of the customer you'll manage. If you already have API access, you'll see your existing Developer Token in the Developer Center under account details.
If not, click Request Token in the Developer Center. Fill in the required information about how you'll use the API. For first-party use (your own accounts), the Developer Token is typically issued instantly. For agencies or third parties managing other advertisers' accounts, approval can take up to five business days and may require additional review.
Save the Developer Token securely. You'll send it as the DeveloperToken header on every API call.
2. Register an app in Microsoft Entra ID
Go to the Azure portal or Microsoft Entra admin center and navigate to App registrations. Click New registration.
Configure:
- Name: something descriptive (e.g.,
My App – Microsoft Advertising Integration) - Supported account types: for SaaS that should work for any advertiser, select "Accounts in any organizational directory and personal Microsoft accounts" (multitenant + MSA). Internal-only integrations can use single-tenant.
- Redirect URI: select Web and add your OAuth callback URL (e.g.,
https://your-app.com/oauth/callbackfor production,http://localhost:8080for local development)
After registration, record the Application (client) ID — this is your client_id.
Under Certificates & secrets, click New client secret, create a secret, and copy the value immediately. This is your client_secret. Microsoft only shows it once.
3. Build the authorization URL
Direct users to Microsoft's authorization endpoint:
https://login.microsoftonline.com/common/oauth2/v2.0/authorize
?client_id={YOUR_CLIENT_ID}
&response_type=code
&redirect_uri={YOUR_REDIRECT_URI}
&scope=https://ads.microsoft.com/ads.manage offline_access
&state={CSRF_TOKEN}
The user signs in with their Microsoft Advertising credentials, sees the consent screen describing what your app is requesting, and clicks Accept. Microsoft redirects to your redirect_uri with ?code={AUTH_CODE}&state={CSRF_TOKEN}.
Validate the state parameter against the value you generated.
4. Exchange the authorization code for tokens
POST to Microsoft's token endpoint:
POST https://login.microsoftonline.com/common/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={YOUR_CLIENT_ID}
&client_secret={YOUR_CLIENT_SECRET}
&grant_type=authorization_code
&code={AUTH_CODE}
&redirect_uri={YOUR_REDIRECT_URI}
The response contains a short-lived access token (one hour) and a long-lived refresh token. Store both per-tenant alongside the Developer Token.
5. Discover Customer and Account IDs
Microsoft Advertising's hierarchy is Customer → Account → Campaign → Ad Group → Ad. The user you just authorized may have access to one or many Customers, and each Customer contains one or more Accounts.
Call the Customer Management Service to enumerate what the authenticated user can access, store the resulting CustomerId and AccountId values per tenant, and use them on subsequent API calls.
6. Make authenticated API calls
Every Microsoft Advertising REST API request requires three headers together:
Authorization: Bearer {access_token}
DeveloperToken: {developer_token}
CustomerId: {customer_id}
CustomerAccountId: {account_id}
Missing any one of these produces an auth error that looks different depending on which is missing — see the gotcha section.
When the access token expires (one hour), refresh it by POSTing to the same token endpoint with grant_type=refresh_token and your refresh token. Save the new access token; the refresh token usually stays the same but can rotate.
The gotcha: Microsoft Advertising's auth model has its own quirks
Don't build against SOAP for new integrations. This is the single most important 2026 decision. SOAP enters feature freeze October 1, 2026 — new campaign types and reporting features go REST-only — and is fully decommissioned January 31, 2027. Some Microsoft documentation still references SOAP-era patterns and the bingads-13 URL path. For new work, target the REST API. SOAP is for maintaining existing systems only until migration is complete.
Three credentials, three different failure modes. Microsoft Advertising's auth requires the Developer Token, the OAuth access token, and the CustomerId/AccountId headers — all three on every call. Missing the access token produces 401 UNAUTHENTICATED. Missing the Developer Token or having it disabled produces 403 PERMISSION_DENIED with developer-token-specific error messages. Missing or wrong Customer/Account IDs produces 403 with permission-related messaging that looks like an access problem but is actually a wrong-ID problem.
Service principals don't work. Unlike Microsoft Graph and many other Microsoft APIs, Microsoft Advertising does not support app-only / service-principal OAuth flows. Delegated user OAuth — where a real Microsoft Advertising user signs in and grants consent — is the only supported pattern. Engineers familiar with Microsoft Graph's broad service-principal support will hit this wall when they try to apply the same pattern.
Azure AD vs. Microsoft Entra ID naming. Microsoft rebranded Azure Active Directory to Microsoft Entra ID, but the technical documentation often still uses both names interchangeably. The portal UI may say "Microsoft Entra admin center" while the docs say "Azure Active Directory." They refer to the same system. The OAuth endpoint domain is still login.microsoftonline.com regardless of which name you encounter.
Sandbox is a separate environment with separate credentials. Unlike Google Ads (which uses test accounts inside the production API), Microsoft Advertising's sandbox has its own URL, its own developer token (often a shared multi-user token for testing), its own user accounts (typically with an _sbx suffix), and its own Microsoft Advertising web UI. Switching between sandbox and production means switching both the API endpoint and the developer token — the OAuth mechanics stay the same but the credentials don't transfer.
Security and credential handling
Store all three credentials in a proper secret manager. Developer Token, OAuth client secret, refresh tokens — all are sensitive credentials. AWS Secrets Manager, Azure Key Vault, GCP Secret Manager. Never commit them. Rotate the client secret every 6–12 months or on team changes.
Refresh proactively. Access tokens expire after one hour. Refresh at the 55-minute mark with retry logic and exponential backoff on failures.
Track refresh-token state per tenant. Microsoft sometimes rotates refresh tokens. Always persist the latest one from each refresh response.
Use least-privilege account types. For SaaS, the multitenant + MSA app registration setting is correct for broad compatibility but doesn't mean your access is unrestricted — each user still grants consent individually, and that consent is what determines effective access.
Monitor for token-revocation patterns. Repeated 401 errors during refresh usually mean the user revoked consent or the refresh token was invalidated — not a transient network issue. Re-prompt the user to re-authorize rather than retrying indefinitely.
Is there an API-key alternative?
No. Microsoft Advertising does not support API keys, basic authentication, or service-principal flows. The only path is the three-credential pattern: Developer Token + OAuth client credentials + delegated user access/refresh tokens. Every architecture decision in your integration — multi-tenant storage, refresh scheduling, sandbox-vs-production switching, customer onboarding flow — flows from that pattern.
Frequently asked questions
SOAP or REST in 2026? REST. SOAP is in feature freeze as of October 1, 2026, and fully decommissioned on January 31, 2027. Some campaign types and reporting features are already REST-only. If you're maintaining a legacy SOAP integration, you have a hard deadline to migrate.
How does this compare to Google Ads auth? Both APIs require a Developer Token plus OAuth, and both use a Customer-based hierarchy — but the resemblance ends at the concept level. Microsoft's identity platform (Entra ID) is different from Google's, the scope format is different (ads.microsoft.com/ads.manage vs googleapis.com/auth/adwords), Microsoft has a real separate sandbox environment while Google has test accounts inside production, and Microsoft Advertising doesn't support service-principal flows while Google Ads allows some limited server-to-server patterns. Knowing Google Ads helps you understand the model but doesn't translate to working code.
Can I use service principals or client-credentials flow? No. Microsoft Advertising's published patterns are delegated user OAuth only. App-only tokens that work for Microsoft Graph or other Microsoft APIs are not supported for Microsoft Advertising.
Why am I getting 403 errors even with a valid access token? Three common causes: (1) Developer Token is invalid, disabled, or doesn't match the environment (sandbox token used against production endpoints, or vice versa); (2) the authorized user doesn't have access to the CustomerId or AccountId you're referencing; (3) you're using sandbox accounts against the production API endpoint.
Do I need to apply for a developer token like Google Ads? Sort of, but it's much simpler. For first-party use (managing your own accounts), the Developer Token is typically issued instantly when you click Request Token in the Microsoft Advertising Developer Portal. For agency or tool-provider scenarios, approval can take up to five business days. There's no Google Ads-style test/basic/standard tier system.
Where Unified fits
Unified.to provides a single API across Microsoft Advertising, Google Ads, Meta Ads, LinkedIn Ads, TikTok Ads, Amazon Advertising, Google Campaign Manager 360, Google Display & Video 360, and 7 other advertising integrations — 15 in total — covering campaigns, ad groups, ads, creatives, targeting, and reporting through a normalized data model.
For Microsoft Advertising specifically, Unified handles the three-credential pattern (Developer Token, OAuth credentials, user access tokens), Customer/Account hierarchy discovery, refresh-token management, and the REST API endpoint structure behind a single authorization step. Real Microsoft Advertising objects map to Unified's normalized models: ads_organization (list/get), ads_campaign, ads_group, ads_ad, and ads_creative with full CRUD, plus ads_report and ads_target for reporting and targeting access. The paid-search workflow — campaign creation, ad-group management, keyword and creative updates, performance reporting — is fully supported through normalized endpoints. Vendor-specific endpoints, including the more advanced bid-strategy configurations and the Customer Management Service for hierarchy discovery, are available through pass-through access.
If you're evaluating whether to build Microsoft Advertising integration directly or use a unified API, the question is whether the ongoing maintenance — the SOAP shutdown migration, credential rotation, Entra ID portal changes, future API version transitions — is something your team should own, or something to abstract behind a single connection.