Authentication Methods

PinBridge supports two auth methods:

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

Both can be sent as:

• Authorization: Bearer <token_or_api_key>
• X-API-Key: <api_key>

Accounts can use PinBridge sandbox for integration testing before paying for live API pin creations.

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": "you@example.com",
    "password": "your-strong-password"
  }'

Expected response includes:

• access_token
• expires_in
• user
• organization
• active_project
• projects
• workspace (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": "you@example.com",
    "password": "your-strong-password"
  }'

Save access_token from the response.

3. Verify Session Token

curl https://api.pinbridge.io/v1/auth/me \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

If valid, you get user, organization, active_project, projects, and workspace.

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": "you@example.com"
  }'

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": "<token-from-email>",
    "password": "your-new-strong-password"
  }'

Important:

• POST /v1/auth/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 token 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 <ACCESS_TOKEN>" \
  -d '{"name": "Production Publisher"}'

Important:

• The plaintext api_key is returned once.
• Store it in a secrets manager.
• Do not expose it in browser code.

6. Use the API Key

X-API-Key style:

curl https://api.pinbridge.io/v1/pinterest/accounts \
  -H "X-API-Key: <API_KEY>"

Authorization style:

curl https://api.pinbridge.io/v1/pinterest/accounts \
  -H "Authorization: Bearer <API_KEY>"

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 <ACCESS_TOKEN>" \
  -d '{
    "current_password": "your-current-password",
    "new_password": "your-new-strong-password"
  }'

Request email verification:

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

Verify email token:

curl "https://api.pinbridge.io/v1/auth/email/verify?token=<token-from-email>"

Fetch/update billing profile:

curl https://api.pinbridge.io/v1/auth/profile \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

curl -X PUT https://api.pinbridge.io/v1/auth/profile \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
    "workspace_name": "Acme Publishing",
    "billing_email": "billing@acme.com"
  }'

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 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 Step

Continue with the full hands-on guide:

• Quick Start Tutorial