Pinterest API refresh token error
The common causes of a failed Pinterest token refresh, and how to distinguish an expired refresh token from a revoked connection.
By André LugPinterest issues 30-day access tokens and a 60-day continuous refresh token meant to be indefinitely renewable. A failed refresh almost never means "try again in a minute": the refresh token either genuinely expired after the 60-day window lapsed or was revoked — user disconnect, password change, or Pinterest's own security response — and both cases require a full reconnection through the OAuth consent screen.
Pinterest's current OAuth model, per Pinterest's developer documentation, issues a continuous refresh token: access tokens last 30 days, the refresh token itself lasts 60 days, and using it to mint a new access token is meant to be indefinitely repeatable without the user ever seeing a login screen again. A refresh call that fails against a token this long-lived is worth taking seriously — it almost never means "try again in a minute," and pattern-matching the failure correctly saves a lot of wasted retry attempts.
PostGate handles OAuth, publishing and delivery evidence for every network through one API. Start free or read the docs.
Expired and revoked look identical in the response, but need different fixes
Both cases return an OAuth invalid_grant-style error from the POST /v5/oauth/token endpoint, and the response body alone often can't tell you which one happened. The difference is in what actually needs to happen next:
- Expired — the 60-day refresh window genuinely lapsed, usually because the connected account went dormant and nothing triggered a refresh before the window closed. The fix is a full reconnection through Pinterest's OAuth consent screen; there is no way to extend an already-expired refresh token.
- Revoked — the Pinterest account owner disconnected your app explicitly (from Pinterest's own account settings), changed their Pinterest password, or Pinterest itself invalidated the token as a security response — the company's own docs note it monitors for leaked tokens (for example, committed to a public GitHub repo) and revokes them within 24 hours of detection. This also requires a full reconnection, but is worth surfacing to the account owner differently than a routine expiry, since it usually means something changed on their end deliberately or as a security event.
The practical fix: refresh well before 60 days, not after
Because the refresh token is meant to be continuously renewable, the reliable pattern is proactive: refresh the access token on a schedule well inside the 60-day window — for example every 20 to 30 days — rather than waiting for an access token to expire and refreshing reactively. A refresh call made comfortably inside the window also resets the clock on the refresh token itself, so a consistently active integration should rarely see the 60-day ceiling in the first place.
curl -X POST https://api.pinterest.com/v5/oauth/token \
-H "Authorization: Basic $BASE64_APP_ID_AND_SECRET" \
-d grant_type=refresh_token \
-d refresh_token=$STORED_REFRESH_TOKENCould it be a scope problem instead?
A refresh can also fail if the app's registered scopes changed since the token was issued, or if the request omits a scope the original grant included. This surfaces differently from a plain expiry/revocation — check the app's current scope configuration in the Pinterest developer dashboard against what was requested when the connection was first made, before treating every refresh failure as a dead connection requiring reconnect.
How does PostGate handle this?
PostGate refreshes Pinterest access tokens proactively in the background well before the 60-day window, so a healthy connection normally never surfaces a refresh failure at all. When a refresh does fail, PostGate marks the profile reauth_required rather than silently letting the next scheduled Pin fail against a dead token — see profile health for how that state is reported, and Pinterest API Standard Access Approval for how the connection is established in the first place.
Frequently asked questions
How long do Pinterest API tokens last?
Per Pinterest's developer documentation, access tokens last 30 days and the refresh token lasts 60 days — and using the refresh token to mint a new access token is meant to be indefinitely repeatable without the user seeing a login screen again. A refresh made comfortably inside the window also resets the clock on the refresh token itself, so an active integration should rarely hit the 60-day ceiling.
How do I tell an expired Pinterest refresh token from a revoked one?
Often you cannot from the response alone — both return an OAuth invalid_grant-style error from POST /v5/oauth/token. Expired means the 60-day window lapsed, usually on a dormant account. Revoked means the owner disconnected your app, changed their password, or Pinterest invalidated the token as a security response. Both need full reconnection, but revocation is worth surfacing to the account owner differently than a routine expiry.
Does Pinterest revoke leaked API tokens?
Yes. Pinterest's own docs note that it monitors for leaked tokens — for example, tokens committed to a public GitHub repository — and revokes them within 24 hours of detection. A refresh failure after such a revocation requires a full reconnection; there is nothing to retry.
How often should I refresh a Pinterest access token?
Proactively, on a schedule well inside the 60-day window — for example every 20 to 30 days — rather than waiting for an access token to expire and refreshing reactively. Because each refresh resets the refresh token's own clock, this pattern means a consistently active integration should never see the 60-day ceiling at all.
Can a scope change cause a Pinterest refresh failure?
Yes. A refresh can fail if the app's registered scopes changed since the token was issued, or if the request omits a scope the original grant included. This surfaces differently from a plain expiry or revocation — check the app's current scope configuration in the Pinterest developer dashboard against what was requested at connection time before treating every refresh failure as a dead connection.
