Pinterest API v5 Transition: The Complete Developer Guide

Everything you need to migrate from Pinterest API v4 to v5 — board access, refresh tokens, SDK setup, and how Ayrshare handles the complexity for you.

Why You Need to Migrate to Pinterest API v5

If you are building or maintaining a social media scheduling tool, analytics dashboard, or any automation that touches Pinterest, you are required to use the Pinterest API v5. Pinterest deprecated v4 in June 2024, and any integration still relying on v4 endpoints will encounter authentication failures, broken board access, and missing functionality.

This Pinterest API v5 guide covers the full migration surface: what changed in authentication, how board access and scopes work, the new refresh token model, official SDK availability, and how Ayrshare abstracts the entire transition into a single API call.

What Changed: Pinterest API v5 vs v4

Pinterest API v5 is not a minor version bump. It represents a ground-up rethink of how developers authenticate, access boards, and manage tokens. Here is the full comparison:

The single biggest impact for most integrations is the shift from short-lived access tokens to a proper refresh token model, and the introduction of explicit scopes for board access.

Authentication Changes: From Implicit Flow to PKCE

Pinterest API v4 used an OAuth 2.0 implicit flow, which returned an access token directly in the redirect URL fragment. This was convenient but insecure — access tokens were exposed in browser history, server logs, and referrer headers.

The v5 Authorization Code Flow with PKCE

Pinterest API v5 requires the OAuth 2.0 authorization code flow with PKCE (Proof Key for Code Exchange). This is the current industry standard and is required for all server-side and mobile integrations.

The flow works as follows:

1. Your application generates a code_verifier (a random 43–128 character string) and derives a code_challenge from it using SHA-256.
   
2. You redirect the user to Pinterest’s authorization URL, including the code_challenge and requested scopes.
   
3. Pinterest redirects back with a short-lived authorization_code in the query string.
   
4. Your server exchanges the authorization_code + code_verifier for an access token and a refresh token.
   

Refresh Tokens: The New Token Lifecycle

One of the most significant Pinterest API changes in v5 is the introduction of refresh tokens. In v4, your only option was to send users back through the OAuth flow when their access token expired. In v5, you can silently refresh tokens on the server side — but only if you plan for it correctly.

Token Lifespans in Pinterest API v5

• Access token: Access tokens expire after 1 hour (3600 seconds).
  
• Refresh token: Refresh tokens expire after 365 days of inactivity.
  
• Rolling expiry: The refresh token expiry resets on every successful refresh.
  
• Hard expiry: If a user revokes access or does not re-authorize within 365 days, the refresh token is invalidated and a full re-auth is required.
  

Implementing the Refresh Flow (Node.js)

const refreshPinterestToken = async (refreshToken) => { 
  const response = await fetch( 
     'https://api.pinterest.com/v5/oauth/token', 
     { 
       method: 'POST', 
       headers: { 
         'Content-Type': 'application/x-www-form-urlencoded', 
         Authorization: `Basic ${Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64')}`, 
       }, 
       body: new URLSearchParams({ 
         grant_type: 'refresh_token', 
         refresh_token: refreshToken, 
       }) 
     } 
   ); 
   const data = await response.json(); 
   // CRITICAL: Store the NEW refresh_token — Pinterest rotates it on each refresh 
   return { accessToken: data.access_token, refreshToken: data.refresh_token }; 
};

const refreshPinterestToken = async (refreshToken) => { 
  const response = await fetch( 
     'https://api.pinterest.com/v5/oauth/token', 
     { 
       method: 'POST', 
       headers: { 
         'Content-Type': 'application/x-www-form-urlencoded', 
         Authorization: `Basic ${Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64')}`, 
       }, 
       body: new URLSearchParams({ 
         grant_type: 'refresh_token', 
         refresh_token: refreshToken, 
       }) 
     } 
   ); 
   const data = await response.json(); 
   // CRITICAL: Store the NEW refresh_token — Pinterest rotates it on each refresh 
   return { accessToken: data.access_token, refreshToken: data.refresh_token }; 
};

Board Access: Scopes and Write Permissions

Pinterest API v4 gave read-only board access by default with no clear mechanism for write access. Pinterest API v5 introduces a proper OAuth scope system for board access.

Available Pinterest API v5 Board Scopes

• boards:read — Read all boards and pins on the account.
  
• boards:read_secret — Read boards and pins in secret (private) boards.
  
• boards:write — Create, update, and delete boards.
  
• boards:write_secret — Create, update, and delete secret boards.
  
• pins:read_secret — Read all pins including those on secret boards.
  
• pins:write — Create, update, and delete pins.
  

To request board write access, your OAuth authorization URL must explicitly include the scope:

const authUrl = `https://www.pinterest.com/oauth/
  ?client_id=${CLIENT_ID}
  &redirect_uri=${encodeURIComponent(REDIRECT_URI)}
  &response_type=code
  &scope=boards:read,boards:write,pins:write
  &code_challenge=${codeChallenge}
  &code_challenge_method=S256`;

const authUrl = `https://www.pinterest.com/oauth/
  ?client_id=${CLIENT_ID}
  &redirect_uri=${encodeURIComponent(REDIRECT_URI)}
  &response_type=code
  &scope=boards:read,boards:write,pins:write
  &code_challenge=${codeChallenge}
  &code_challenge_method=S256`;

Official SDK Support in Pinterest API v5

One of the most developer-friendly Pinterest API changes is the introduction of officially maintained SDKs. Pinterest API v4 had no official SDK, forcing teams to maintain custom HTTP clients and handle auth edge cases manually.

Available Official SDKs

• Python: pip install pinterest-python-sdk
  
• Node.js / TypeScript: npm install pinterest-api-sdk
  
• Java: Available via Maven / Gradle
  
• iOS (Swift): Available via CocoaPods
  
• Android (Kotlin): Available via Maven
  

Node.js SDK: Posting a Pin

const { PinterestClient } = require('pinterest-api-sdk');

const client = new PinterestClient({ accessToken: ACCESS_TOKEN });

const pin = await client.pins.create({
  board_id: 'YOUR_BOARD_ID',
  title: 'My Automated Pin',
  description: 'Created via Pinterest API v5',
  media_source: {
    source_type: 'image_url',
    url: 'https://example.com/image.jpg'
  }
});

const { PinterestClient } = require('pinterest-api-sdk');

const client = new PinterestClient({ accessToken: ACCESS_TOKEN });

const pin = await client.pins.create({
  board_id: 'YOUR_BOARD_ID',
  title: 'My Automated Pin',
  description: 'Created via Pinterest API v5',
  media_source: {
    source_type: 'image_url',
    url: 'https://example.com/image.jpg'
  }
});

While the SDKs eliminate a lot of boilerplate, they do not handle token refresh, scope errors, or retry logic automatically. You still need to build that layer yourself — or use Ayrshare.

The Ayrshare Solution: Pinterest API v5 Without the Complexity

Ayrshare was built so that developers never need to touch Pinterest’s OAuth layer, board scopes, or token rotation logic directly. When you post to Pinterest through Ayrshare, we handle:

• OAuth lifecycle: Full PKCE-based OAuth flow and callback handling
  
• Token refresh: Automatic silent refresh before every request; re-auth prompts when refresh tokens expire
  
• Board access: Board scope validation at request time, not at publish time
  
• SDK-agnostic: Correct API version routing — all traffic uses v5 endpoints
  
• Resilience: Rate limit management and retry logic built in
  

Code Comparison: Native v5 vs Ayrshare

// ✅ With Ayrshare — zero token or board scope management
const ayrshare = require('ayrshare-node')('YOUR_API_KEY');

const post = await ayrshare.post({
  post: 'Automated with Ayrshare + Pinterest API v5.',
  mediaUrls: ['https://example.com/image.jpg'],
  platforms: ['pinterest'],
  pinterestOptions: { boardId: 'YOUR_BOARD_ID' }
});

// ✅ With Ayrshare — zero token or board scope management
const ayrshare = require('ayrshare-node')('YOUR_API_KEY');

const post = await ayrshare.post({
  post: 'Automated with Ayrshare + Pinterest API v5.',
  mediaUrls: ['https://example.com/image.jpg'],
  platforms: ['pinterest'],
  pinterestOptions: { boardId: 'YOUR_BOARD_ID' }
});

Five lines. No PKCE, no refresh token storage, no scope management, no SDK version pinning.

Frequently Asked Questions about Pinterest API v5

Stop Rebuilding OAuth for Every Platform

The Pinterest API v5 transition is a real migration with breaking changes across authentication, token management, board access scopes, and SDKs. Every SaaS team that builds on top of the Pinterest API natively will spend sprint cycles re-implementing flows that Pinterest has fundamentally redesigned.

Ayrshare handles the Pinterest API changes — and every future breaking change across all major social platforms — so your engineering team can focus on your product.

Start for free with Ayrshare.