How to Get Your Pinterest Ads API Key
May 29, 2026
Pinterest doesn't issue a single "API key." It issues two completely different credentials for two completely different jobs, and confusing them is the single most common cause of 401 and 403 errors in Pinterest integrations:
- OAuth 2.0 credentials (client ID + secret) from the Pinterest Developer Portal — used for the Marketing API: campaigns, ad groups, ads, creatives, reporting, catalogs, and most read/write operations against Pinterest's v5 API.
- A Conversions API (CAPI) token generated inside Pinterest Ads Manager — used only for server-side conversion event tracking, scoped to a specific ad account and tag.
If you're building a general Pinterest Ads integration (campaign management, reporting, creative uploads), you need OAuth credentials. If you're sending server-side conversion events for attribution, you need a CAPI token. Most production integrations need both, generated through different flows and stored separately.
This guide covers the 2026 process for getting Pinterest Ads API credentials: registering your app in the Pinterest Developer Portal, navigating the Trial → Standard access tier system, requesting the right OAuth scopes, and generating CAPI tokens when you need server-side conversion tracking.
Key takeaways
- Two credential systems, two purposes. OAuth credentials for the Marketing API; CAPI tokens for server-side conversion events. They are not interchangeable.
- The current Pinterest API is v5, with the base URL
https://api.pinterest.com/v5/...and a separate sandbox athttps://api-sandbox.pinterest.com/v5/.... - Pinterest's access tier model is Trial → Standard, similar in spirit to Meta's app review but with a demo-video approval process. Trial allows mostly reads; Standard is required for production writes.
- App registration requires a Pinterest Business account. Consumer Pinterest accounts cannot register apps.
- Use-case-based scopes:
ads:read,ads:write,pins:read,pins:write,user_accounts:read,catalogs:read,catalogs:write, plus board variants. Request only what you need. - Ad accounts are scoped under business / user accounts. OAuth tokens are user-centric — the token represents a user's access to one or more ad accounts, not an app-wide identity (different from Meta's Business Manager system-user pattern).
- Marketing API connections typically require yearly re-authorization for long-running SaaS integrations.
Before you start
You'll need:
- A Pinterest Business account (not a consumer account) — required to register a developer app
- A Pinterest Ads Manager account with at least one ad account created
- Admin access to the ad account if you'll be generating CAPI tokens
- A privacy policy URL to provide during app registration
- A demo video plan if you'll need Standard access — what features your app uses, how the OAuth flow looks, and the core API action you're demonstrating
If you skip the demo video planning and try to apply for Standard access later, the most common rejection reasons in 2026 are: demo doesn't show the full OAuth consent flow, or demo doesn't clearly show a Pinterest API action being performed. Plan the recording before you submit.
Step-by-step: creating Pinterest Ads API credentials in 2026
1. Create a developer account
Go to developers.pinterest.com and sign in with your Pinterest Business account. Click Create your developer account and complete the setup.
2. Register your app
From the developer dashboard, go to My apps → Connect app. Fill in:
- App name and company name
- Website URL or app link
- Privacy policy URL (required)
- App purpose and developer purpose — short descriptions of what you're building
- Selected use cases — Pinterest categorizes APIs by use case (Ads, Conversions, Content, Analytics). Select the ones your integration needs.
- Redirect URIs for OAuth callbacks
Unlike some platforms, Pinterest doesn't distinguish between native, web, and service app types — it's a single OAuth client concept that you configure based on use case and audience.
After submitting, your app is granted Trial access.
3. Build the OAuth authorization flow
Pinterest uses OAuth 2.0 authorization-code flow. Direct users to:
https://www.pinterest.com/oauth/
?client_id={YOUR_CLIENT_ID}
&response_type=code
&redirect_uri={YOUR_REDIRECT_URI}
&scope=ads:read,ads:write,user_accounts:read
&state={CSRF_TOKEN}
The user signs in, sees the consent screen describing what your app is requesting, and clicks Authorize. Pinterest redirects to your redirect_uri with ?code={AUTH_CODE}&state={CSRF_TOKEN}.
Exchange the code at https://api.pinterest.com/v5/oauth/token for an access token and refresh token, sending your client ID, client secret, the code, and redirect URI.
4. Request Standard access for production writes
Trial access is sufficient for development but generally does not permit write operations like creating campaigns, ads, or pins programmatically. For production use, apply for Standard access through the developer dashboard.
The approval process requires submitting a demo video showing:
- The full OAuth authorization-code flow, including the user landing on Pinterest's consent screen and granting access
- At least one core API action — typically the most representative write operation for your use case (creating a campaign, creating a pin, etc.)
Standard approval is granted per use case. If you have Standard for Ads but later want to add Conversions or Content management, you may need separate approval for those.
5. Generate a CAPI token (only if you need server-side conversion tracking)
If your integration sends server-side conversion events for attribution, you need a separate CAPI token. This is not generated through the Developer Portal — it's generated inside Pinterest Ads Manager:
- Sign in to Pinterest Ads Manager with admin access to the relevant ad account
- Navigate to Conversions or Conversions API under the Manage Business section
- Click Set up API to start the Conversions API configuration flow
- Click Generate new token — Pinterest produces a token string scoped to that specific ad account and tag
You'll also need the Tag ID (from Manage Business → Pinterest tag) and the Advertiser / Ad Account ID (from Manage Business → Assets → Ad account) — most CAPI integrations require all three together.
The CAPI token is used only for the conversion events endpoints. Using it against general Marketing API endpoints (campaigns, ads, reporting) produces 401 errors.
6. Make authenticated API calls
For the Marketing API, every request to https://api.pinterest.com/v5/... includes:
Authorization: Bearer {oauth_access_token}
For Conversions API events, requests to /v5/ad_accounts/{ad_account_id}/events include the CAPI token in the Authorization header instead of the OAuth bearer token.
Access tokens expire and need refresh through the standard OAuth refresh-token flow. Pinterest doesn't publish exact lifetimes prominently, but plan for proactive refresh and handle 401s with a refresh-then-retry pattern.
The gotcha: Pinterest's auth model has its own quirks
The two-credential confusion is the #1 issue. Engineers building both campaign management and conversion tracking try to use one credential for both. The Marketing API requires OAuth bearer tokens. The Conversions API requires the CAPI token generated in Ads Manager. They're issued through different flows, look different, and produce 401/403 errors when used in the wrong context.
Trial access blocks writes. Pinterest's tier model means most POST operations — creating campaigns, ads, pins — return 403 errors while you're on Trial access, even with valid OAuth credentials and correct scopes. Confirm your access tier before debugging permission errors.
The demo video is the production gate. Standard approval depends almost entirely on the demo video clearly showing two things: the OAuth consent flow from the user's perspective, and a successful core API action. The most common rejection patterns in 2026 are "demo did not show the full OAuth flow" and "demo did not show Pinterest API integration." Record carefully.
User-centric OAuth, not Business Manager. Unlike Meta, Pinterest doesn't have a Business Manager system-user model for app-to-app access. The OAuth token represents a user, and that user's access determines what ad accounts the integration can reach. For multi-tenant SaaS, this means each customer's authorizing user becomes the effective access ceiling for your integration's view into their data.
Yearly re-authorization. Pinterest Marketing API connections typically require periodic re-authorization for long-running integrations — third-party integration docs reference yearly cycles. Plan for re-auth prompts and store enough state to resume gracefully when tokens are revoked.
Sandbox is a separate environment. api-sandbox.pinterest.com/v5/... is distinct from production. The OAuth credentials and access tier may overlap, but the data and ad accounts don't. Use sandbox for development and recording your Standard-access demo video.
Security and credential handling
Store OAuth client secrets and CAPI tokens in a proper secret manager. Both are sensitive credentials. AWS Secrets Manager, Azure Key Vault, GCP Secret Manager. Never commit them.
Refresh OAuth tokens proactively. When access tokens approach expiration, refresh ahead of expiry with retry logic and exponential backoff on failures.
Handle yearly re-authorization gracefully. For SaaS integrations, design your re-auth UX so that customers can renew without losing their connection state — store enough metadata (ad account IDs, last-sync timestamps, configuration) outside the token itself so renewal is just a token swap.
Audit ad account access regularly. OAuth tokens tied to individual users can become stale when those users leave or change roles. Periodically validate that your stored tokens still resolve to the ad accounts the integration was configured against.
Rate limit defensively. Pinterest's published rate limits start around 1,000 requests per hour per app/user combination, with higher allotments for Standard-access apps with demonstrated production use. Implement client-side rate limiting and respect 429 responses with exponential backoff — don't tight-loop on retry.
Is there an API-key alternative?
For the Marketing API: no. OAuth 2.0 authorization-code flow is the only path. There are no static API keys, no basic authentication, no service-principal flows.
For the Conversions API: yes, the CAPI token is essentially a static credential — but it's scoped to a single ad account and tag, used only for server-side event tracking, and not interchangeable with OAuth tokens for other Marketing API operations.
Frequently asked questions
What's the difference between Pinterest's API model and Meta Ads? Both are "paid social" APIs but the patterns differ. Meta uses Business Manager as a hub for ad accounts and pages, supports long-lived system-user tokens for server-to-server work, and has a granular per-permission review process. Pinterest is more user-centric: OAuth tokens represent a user's access to ad accounts, there's no Business Manager equivalent, and the production gate is a single demo-video approval per use case rather than per-permission feature reviews. Knowing Meta helps with the concept but doesn't translate to working Pinterest code.
Do I need Standard access to read data? Mostly no. Trial access generally permits read operations — listing campaigns, fetching reports, reading boards. Standard access is required for write operations like creating campaigns, ads, or pins. If your integration is read-only (dashboards, analytics, reporting), Trial may be sufficient for production.
Why am I getting 403 errors with valid OAuth tokens? Three common causes: (1) your app is still on Trial access and you're attempting a write operation, (2) your token doesn't have the right scope for the endpoint (e.g., calling ads:write endpoints with a token that only has ads:read), or (3) the authorizing user doesn't have sufficient permissions on the target ad account (Analyst, Campaign, or Admin roles all carry different access levels in Pinterest).
Can the same OAuth client manage multiple customers' ad accounts? Yes — that's the standard pattern for SaaS. The same OAuth client (client ID/secret) can authorize many users, each with their own access to their own ad accounts. Each customer goes through the OAuth flow independently, and your backend stores per-customer access tokens and refresh tokens.
What happens when a user revokes consent? Your stored access and refresh tokens stop working — refresh attempts return 401 errors. Detect repeated refresh failures, mark the connection as needing re-authorization, and prompt the customer to reconnect. Don't retry indefinitely against an invalidated token.
Where Unified fits
Unified.to provides a single API across Pinterest Ads, Meta Ads, LinkedIn Ads, TikTok Ads, Google Ads, Microsoft Advertising, Amazon Advertising, Google Campaign Manager 360, Google Display & Video 360, and 6 other advertising integrations — 15 in total — covering campaigns, ad groups, ads, creatives, targeting, and reporting through a normalized data model.
For Pinterest Ads specifically, Unified handles OAuth credentials and refresh, scope routing, ad-account-level access scoping, and the v5 endpoint structure behind a single authorization step. Real Pinterest 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-social workflow — campaign creation, ad group management, creative uploads, performance reporting — is supported through normalized endpoints. Vendor-specific endpoints including catalogs management, the Conversions API for server-side event tracking, and the more advanced shopping-feed configurations are available through pass-through access.
If you're evaluating whether to build Pinterest Ads integration directly or use a unified API, the question is whether the ongoing maintenance — credential rotation, yearly re-auth handling, demo-video resubmissions, and managing both OAuth and CAPI credential systems — is something your team should own, or something to abstract behind a single connection.