Sandbox

The sandbox is a separate project where you can build and test an integration without publishing anything to Pinterest. It simulates the whole publish flow so you can develop confidently, then flip to production when you are ready.

What the sandbox simulates

When you publish in the sandbox, PinBridge does not call Pinterest at all. Instead:

• Publishing is simulated locally. The pin still flows through the normal queue and reaches published, but no real Pinterest write happens.
• You get a fake pin ID. The simulated pin gets a deterministic 18-digit numeric pinterest_pin_id that echoes your board, title, and link back, so you can exercise your success-handling code.
• No real Pinterest and no OAuth token. The simulated publish path never uses an access token or the network.
• Board writes are disabled by default. Creating or deleting boards in the sandbox returns 403 sandbox_board_writes_disabled. You publish to a simulated board ID that PinBridge fills in for you at pin-create time.
• Deletes are hard deletes. In production, deleting a pin is a soft delete. In the sandbox, deletes remove the record for real, which keeps a test project tidy.

Because publishing is simulated by default, a sandbox pin is “published” as fast as the worker picks it up. It is not synchronous in the API response, but it skips the network round trip, token refresh, and per-account rate limiter. See the pin state machine for the states a pin moves through.

You need a user session, not just an API key

Creating, switching, and resetting projects act on your organization, so they require a user-session token in Authorization: Bearer <jwt>, not an API key. These project endpoints reject API keys. (Once you are publishing inside the sandbox, individual pin calls use an API key as usual, see below.)

Get a session token by logging in (POST /v1/auth/login) or from the dashboard. See Core concepts for how the two auth styles differ.

Create a sandbox project

Creating a sandbox is idempotent. If a sandbox already exists for your organization, you get it back.

curl:

curl -sS -X POST https://api.pinbridge.io/v1/projects/sandbox \
  -H "Authorization: Bearer $PINBRIDGE_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My sandbox"}'

The name field is optional. The response is your projects context, listing the organization, the active project, and all projects including the new sandbox.

Expected response (trimmed):

{
  "active_project": { "id": "7b1e4c9a-0d5f-4e2b-9a63-4d8f2b6e0c19", "environment": "production" },
  "projects": [
    { "id": "7b1e4c9a-0d5f-4e2b-9a63-4d8f2b6e0c19", "name": "Production", "environment": "production" },
    { "id": "2a6d8f1b-5c3e-4a9d-b7f2-8e4c0a6b1d35", "name": "My sandbox", "environment": "sandbox" }
  ]
}

Note that creating the sandbox does not move you into it. active_project is still production. Switch into it next.

Python SDK (authenticate with the session token, not an API key):

from pinbridge_sdk import PinbridgeClient

with PinbridgeClient(bearer_token="$PINBRIDGE_SESSION_TOKEN") as client:
    ctx = client.projects.create_sandbox()  # optionally pass {"name": "My sandbox"}
    sandbox = next(p for p in ctx.projects if p.environment == "sandbox")
    print("sandbox project id:", sandbox.id)

Switch into the sandbox

Switching projects is how you enter the sandbox. It returns a new access token whose claims include the environment. In other words, the environment travels in the JWT, not in a per-request header. Use the returned token for everything you do in the sandbox.

curl:

curl -sS -X POST https://api.pinbridge.io/v1/projects/switch \
  -H "Authorization: Bearer $PINBRIDGE_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "2a6d8f1b-5c3e-4a9d-b7f2-8e4c0a6b1d35"}'

Expected response (trimmed):

{
  "active_project": { "id": "2a6d8f1b-5c3e-4a9d-b7f2-8e4c0a6b1d35", "environment": "sandbox" },
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer",
  "expires_in": 3600
}

Python SDK:

from pinbridge_sdk import PinbridgeClient

with PinbridgeClient(bearer_token="$PINBRIDGE_SESSION_TOKEN") as client:
    switched = client.projects.switch({"project_id": "2a6d8f1b-5c3e-4a9d-b7f2-8e4c0a6b1d35"})
    client.set_bearer_token(switched.access_token)  # now scoped to the sandbox

Publish in the sandbox

Once you are in the sandbox you publish exactly as you would in production. Point your requests at the sandbox: either keep using the switched session token, or create an API key while in the sandbox project and use that key’s X-API-Key for pin calls. An API key created in the sandbox project is scoped to the sandbox, so pins you publish with it are simulated.

This is what makes the sandbox convenient for tools that only take an API key, like the n8n node: set a sandbox-scoped API key as the apiKey in the pinBridgeApi credential and your workflow publishes into the sandbox. The n8n node has no project-management action, so create and switch the sandbox through the API or dashboard first, then hand n8n the sandbox key. See Publish your first pin.

A simulated pin reaches published and carries a fake pinterest_pin_id. Nothing appears on Pinterest.

Reset the sandbox

Resetting wipes the sandbox project’s data (its pins, schedules, connected accounts, webhooks, API keys, usage, and uploaded assets) so you can start clean. It does not touch production.

curl:

curl -sS -X POST https://api.pinbridge.io/v1/projects/sandbox/reset \
  -H "Authorization: Bearer $PINBRIDGE_SESSION_TOKEN"

Python SDK:

from pinbridge_sdk import PinbridgeClient

with PinbridgeClient(bearer_token="$PINBRIDGE_SESSION_TOKEN") as client:
    client.projects.reset_sandbox()

If there is no sandbox project to reset, this returns 404.

Moving to live

When your integration works in the sandbox, switching to production is the same switch operation, pointed at your production project:

curl -sS -X POST https://api.pinbridge.io/v1/projects/switch \
  -H "Authorization: Bearer $PINBRIDGE_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "7b1e4c9a-0d5f-4e2b-9a63-4d8f2b6e0c19"}'

Then use a production API key for publishing. Before you go live:

• Connect a real Pinterest account in your production project. Sandbox connections do not carry over.
• Swap any sandbox API key for a production key in your app, n8n credential, or scripts.
• Remember that production pins count against your monthly pin quota and are soft-deleted rather than hard-deleted.

Common errors and troubleshooting

• 401 Invalid or missing access token on a project endpoint. You sent an API key. Create, switch, and reset need a user-session JWT in Authorization: Bearer.
• 403 sandbox_board_writes_disabled when creating or deleting a board in the sandbox. Board writes are off by default. Publish to the simulated board ID instead.
• 404 Sandbox project not found on reset. Create the sandbox first.
• Pins publish to real Pinterest when you expected simulation. Confirm your token or API key is scoped to the sandbox project, not production. Check active_project.environment after switching.

Next steps

• Core concepts for projects, environments, and the pin state machine.
• Connect Pinterest to add a real account for production.
• Publish your first pin once you are ready to go live.