> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pendpost.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pinterest

> Set up Pinterest board posting with a v5 developer app and OAuth.

The Pinterest lane publishes pins to a board. It publishes only once a Pinterest credential is present in your `.env`; until then the lane is live-but-unauthenticated and waits for you to connect it (set `PENDPOST_MODE=mock` to exercise it through the mock driver).

> [!NOTE]
>
> **Beta lane.** Pinterest is built but not yet live-verified end to end, so treat it as a preview and do not rely on it for guaranteed delivery. The lane loses this badge once it is live-verified.

You own your Pinterest account and are responsible for Pinterest's terms of service. pendpost drafts and schedules, but a human approves before anything goes live.

> [!NOTE]
>
> **Trial access is owner-only.** New Pinterest apps start with Trial access, which can post only to the app owner's own account. Publishing pins for other accounts needs Standard access, a separate Pinterest review. Trial access is enough to publish to your own boards.

## Setup ceremony

The app uses the `boards:read`, `pins:read`, and `pins:write` scopes. The auth command runs a local loopback server to receive the authorization code.

1. **Create a developer app.** Open the [Pinterest developer portal](https://developers.pinterest.com/apps/) and create an app with the v5 API enabled. New apps start with Trial access.
2. **Record the app secret.** Copy the app secret from the app settings and store it. It is used as HTTP Basic auth on the token endpoint.
3. **Add the redirect uri.** In the app settings, add the redirect uri exactly: `http://127.0.0.1:8088/oauth/pinterest/callback`. The auth command runs a local loopback server on that address.
4. **Pick the target board.** Choose the board pins are published to and record its id. The auth command can list your boards after you connect.

Then authorize. It opens the consent screen, exchanges the code for an access and refresh token, and stores the expiry:

```bash theme={null}
node scripts/pinterest-social.mjs auth
```

The access token is short-lived and is refreshed automatically before it expires.

## Environment variables

| Variable | Purpose |
| - | - |
| `PINTEREST_APP_ID` | Your Pinterest app id. |
| `PINTEREST_APP_SECRET` | Your Pinterest app secret (HTTP Basic auth on the token endpoint). |
| `PINTEREST_REDIRECT_URI` | The OAuth redirect uri, `http://127.0.0.1:8088/oauth/pinterest/callback`. |
| `PINTEREST_BOARD_ID` | The board pins are published to. |
| `PINTEREST_ACCESS_TOKEN` | Access token from the auth ceremony (short-lived, refreshed automatically). |
| `PINTEREST_REFRESH_TOKEN` | Refresh token from the auth ceremony. |
| `PINTEREST_TOKEN_EXPIRES_AT` | When the access token expires. |

> [!NOTE]
>
> A lane publishes only once its credential is present. If the Pinterest variables are blank, the Pinterest lane is live-but-unauthenticated and waits for you to connect it. Set `PENDPOST_MODE=mock` to exercise it through the mock driver.

## Validate the lane

A present credential is not the same as a working one. After setup, validate the Pinterest lane in the **Setup** tab, or run a live probe with the `health_recheck` tool, to confirm the credential is live and not just configured. The lane is ready when it reports live.

> [!NOTE]
>
> **Over MCP.** Setup and rotation are an interactive human ceremony; secrets are never written through MCP. An agent can still check status (`account_status`), run a live liveness probe (`health_recheck`), and read non-secret config (`config_get`) over MCP without touching credentials.

## Common failures

| Symptom | Cause | Fix |
| - | - | - |
| The consent screen rejects the redirect uri. | The redirect uri in the app settings does not match the loopback address exactly. | Add `http://127.0.0.1:8088/oauth/pinterest/callback` to the app, with no trailing-slash difference, and retry. |
| Publishing returns a 403 about access level. | The app is in Trial access and is targeting an account other than the app owner. | Publish to the app owner's own boards while in Trial, or apply for Standard access to post more broadly. |
| Posting fails with an expired-token error. | The stored refresh token was revoked or rotated out. | Re-run the auth command to mint a fresh access and refresh token pair. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.