Authentication

Use a JWT for user sessions and an API key for production server-to-server calls.

Authentication methods

PinBridge supports two auth methods:

• A JWT bearer token from POST /v1/auth/register or POST /v1/auth/login.
• An API key from POST /v1/api-keys.

An API key is sent in the X-API-Key header and works for all publishing and read endpoints. A user-session JWT is sent as Authorization: Bearer <token>. A few endpoints, /v1/auth/me and /v1/projects, require a user-session JWT and reject API keys.

You can use the PinBridge sandbox for integration testing before you pay for live pin creations. See Rate limits & quotas for what counts against your quota.

1. Register a user

Use this once per account:

curl -X POST https://api.pinbridge.io/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Jane Doe",
    "email": "[email protected]",
    "password": "your-strong-password"
  }'

The response includes access_token, expires_in, user, organization, active_project, projects, and workspace (a legacy compatibility field).

2. Log in (returning users)

curl -X POST https://api.pinbridge.io/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-strong-password"
  }'

Save access_token from the response.

3. Verify a session token

curl https://api.pinbridge.io/v1/auth/me \
  -H "Authorization: Bearer $PINBRIDGE_JWT"

If the token is valid, you get user, organization, active_project, projects, and workspace. This endpoint requires a user-session JWT and rejects API keys.

4. Recover a password

Request a reset email:

curl -X POST https://api.pinbridge.io/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]" }'

Complete the reset with the token from the emailed link:

curl -X POST https://api.pinbridge.io/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d "{
    \"token\": \"$RESET_TOKEN\",
    \"password\": \"your-new-strong-password\"
  }"

• forgot-password always returns the same success message whether the email exists or not.
• Reset links are single-use and expire automatically.
• The web app exposes the same flow at /forgot-password and /reset-password.

5. Create an API key (recommended for backend jobs)

Use your JWT to create a long-lived API key for server-to-server usage:

curl -X POST https://api.pinbridge.io/v1/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PINBRIDGE_JWT" \
  -d '{ "name": "Production Publisher" }'

The plaintext api_key is returned once. Store it in a secrets manager, and never expose it in browser code.

6. Use the API key

X-API-Key style (recommended):

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

Authorization style:

curl https://api.pinbridge.io/v1/pinterest/accounts \
  -H "Authorization: Bearer $PINBRIDGE_API_KEY"

A first call to GET /v1/pinterest/accounts is the simplest way to confirm a new API key works.

7. Additional auth endpoints

Authenticated password change:

curl -X POST https://api.pinbridge.io/v1/auth/change-password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PINBRIDGE_JWT" \
  -d '{
    "current_password": "your-current-password",
    "new_password": "your-new-strong-password"
  }'

Request email verification, then verify the token:

curl -X POST https://api.pinbridge.io/v1/auth/email/verify/request \
  -H "Authorization: Bearer $PINBRIDGE_JWT"

curl "https://api.pinbridge.io/v1/auth/email/verify?token=$VERIFY_TOKEN"

Fetch or update the billing profile:

curl https://api.pinbridge.io/v1/auth/profile \
  -H "Authorization: Bearer $PINBRIDGE_JWT"

curl -X PUT https://api.pinbridge.io/v1/auth/profile \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PINBRIDGE_JWT" \
  -d '{
    "workspace_name": "Acme Publishing",
    "billing_email": "[email protected]"
  }'

Common auth errors

• 401 Missing API key — no auth header provided.
• 401 Invalid API key — key is wrong or revoked.
• 401 Invalid access token — JWT is malformed, expired, or the workspace is missing.
• 400 Invalid or expired password reset token — reset token is missing, expired, or already used.
• 409 Account already exists — trying to register an existing email.

Security checklist

• Use JWTs for end-user login sessions.
• Use API keys only on trusted backend services.
• Rotate API keys periodically.
• Revoke compromised keys with DELETE /v1/api-keys/{key_id}.
• Never commit tokens or API keys to source control.

Next steps

• Quickstart — connect Pinterest and publish your first pin.
• Rate limits & quotas — token buckets, monthly pin quotas, and billing errors.
• Billing & credits — plans, quota, and credit packs.
• Python SDK — a typed client for the same endpoints.