Connect Pinterest

Before you can publish, PinBridge needs a Pinterest account to publish with. You connect one through Pinterest’s OAuth flow. This page walks the full flow, shows how to reconnect an account whose token has expired, and how to revoke access.

Prerequisites

• An API key (send it in the X-API-Key header). See Core concepts for how projects and API keys fit together.
• A Pinterest account you can log in to and approve access for.
• Your plan’s Pinterest account limit has room. Playground allows 1 connected account; paid plans allow more.

Most people connect an account from the PinBridge dashboard, which runs this flow for you. The steps below are the same flow done through the API, which is useful for automation.

The OAuth flow

There are three steps: get a consent URL, have the user approve on Pinterest, then let PinBridge complete the exchange.

1. Start OAuth

Call the start endpoint. It returns a Pinterest consent URL.

curl:

curl -sS https://api.pinbridge.io/v1/pinterest/oauth/start \
  -H "X-API-Key: $PINBRIDGE_API_KEY"

Expected response (trimmed):

{
  "authorization_url": "https://www.pinterest.com/oauth/?client_id=...&state=..."
}

2. Approve on Pinterest

Open authorization_url in a browser and approve access. Pinterest then redirects back to PinBridge’s callback URL with two query parameters, code and state. In the dashboard flow this redirect is handled for you and the account shows up connected. For a programmatic flow, capture code and state from the redirect.

3. Complete the callback

Complete the exchange by calling the callback with the code and state you received.

curl:

curl -sS "https://api.pinbridge.io/v1/pinterest/oauth/callback?code=$CODE&state=$STATE" \
  -H "X-API-Key: $PINBRIDGE_API_KEY"

Once the callback succeeds, the account is connected. Confirm it by listing your accounts.

4. List connected accounts

curl -sS https://api.pinbridge.io/v1/pinterest/accounts \
  -H "X-API-Key: $PINBRIDGE_API_KEY"

Expected response (trimmed):

[
  {
    "id": "6f1c2e4a-3b7d-4c9e-8a21-5d0f9b3e7c41",
    "username": "your_pinterest_handle",
    "display_name": "Your Brand",
    "scopes": "boards:read,pins:read,pins:write",
    "health_status": "healthy",
    "reconnect_required": false,
    "token_expires_at": "2026-12-01T00:00:00Z",
    "missing_scopes": []
  }
]

The id field is the account_id you pass when publishing a pin. See Core concepts for how accounts, boards, and pins relate.

Python SDK

from pinbridge_sdk import PinbridgeClient

with PinbridgeClient(api_key="$PINBRIDGE_API_KEY") as client:
    # 1) Get the consent URL
    start = client.pinterest.start_oauth()
    print("Open this URL to approve:", start.authorization_url)

    # 2) After the user approves, complete the callback with code + state
    client.pinterest.oauth_callback(code="$CODE", state="$STATE")

    # 3) Confirm the account is connected
    accounts = client.pinterest.list_accounts()
    for a in accounts:
        print(a.id, a.username, a.health_status)

Boards and accounts both live under client.pinterest. There is no client.boards resource.

n8n

The n8n node (n8n-nodes-pinbridge) exposes these under the Connection resource:

• Start OAuth returns the consent URL.
• Complete OAuth Callback takes OAuth Code and OAuth State and finishes the exchange.
• List returns your connected accounts (this is also what the account dropdowns load).
• Revoke disconnects an account by its Connection (connection ID).

The credential type is pinBridgeApi (baseUrl defaults to https://api.pinbridge.io, plus your apiKey), and it authenticates with the X-API-Key header. See Publish your first pin for using the connected account in a workflow.

Reconnecting an expired account

Pinterest tokens do not last forever. PinBridge tracks each account’s health so you can spot one that needs attention before a publish fails.

On each account in GET /v1/pinterest/accounts, watch these fields:

• health_status is healthy when the account is good to publish. It becomes reconnect_required when the account needs to be reconnected.
• reconnect_required is a boolean shortcut for the same thing.
• token_expires_at is when the current access token expires.
• health_message explains what is wrong in plain language, and missing_scopes lists any permissions Pinterest did not grant.

An account whose token has expired and cannot be refreshed, whose access was revoked on Pinterest, or that is missing a required scope will show health_status: "reconnect_required".

To reconnect, run the same OAuth flow again (start, approve, callback) with the same Pinterest account. Approving again issues a fresh token and clears the reconnect flag. If missing_scopes was populated, make sure you approve all the requested permissions this time.

If you try to publish with an account that needs reconnecting, the pin fails with an error_code of token_expired, token_revoked, or scope_missing. See the pin state machine for how those failures surface.

Revoking an account

To disconnect an account, delete it by its account_id.

curl:

curl -sS -X DELETE https://api.pinbridge.io/v1/pinterest/accounts/6f1c2e4a-3b7d-4c9e-8a21-5d0f9b3e7c41 \
  -H "X-API-Key: $PINBRIDGE_API_KEY"

A successful revoke returns 204 No Content.

Python SDK:

from pinbridge_sdk import PinbridgeClient

with PinbridgeClient(api_key="$PINBRIDGE_API_KEY") as client:
    client.pinterest.revoke_account("6f1c2e4a-3b7d-4c9e-8a21-5d0f9b3e7c41")

In n8n, use Connection → Revoke and pick the connection to remove.

Why PinBridge uses shared IPs (and why that’s fine)

A common worry is that PinBridge publishes from shared server IP addresses rather than your home or office IP, and that this might look suspicious to Pinterest. It does not, and here is why.

Pinterest identifies your account by the OAuth token you approved during the flow above, not by the IP address a request comes from. That token is what proves the request is authorized to act on your account. The IP is not part of how Pinterest ties an API request to an account.

PinBridge is a registered Pinterest API application. Traffic from a registered app arriving over shared server IPs is exactly what Pinterest expects from an app that serves many users. Shared IPs are the normal, expected setup for a registered API integration and are not a risk to your account.

So there is nothing to configure here and no reason to avoid publishing through PinBridge on account of IPs. What actually matters is keeping your connection healthy (the health_status above) and staying within your rate and quota limits.

Common errors and troubleshooting

• Invalid OAuth state (400) on the callback. The state value did not match. Start the flow again from step 1 so a fresh state is issued, and complete it in the same session.
• Account shows health_status: "reconnect_required". The token expired, was revoked, or a scope is missing. Reconnect the account (see above) and approve all requested permissions.
• Publishes fail with board_access_denied. The connected account cannot post to that board. Confirm the board belongs to the connected account.
• Pinterest account not found (404) when publishing or revoking. The account_id is wrong or the account was already revoked. List accounts to get the current id.

Next steps

• Core concepts for the object model and pin states.
• Publish your first pin using your connected account.
• Try the sandbox to test publishing without touching real Pinterest.