Team and roles

Invite teammates to your PinBridge organization and give each one the right level of access. This page covers the four roles, exactly what each can do, and how invitations work.

Prerequisites

• Team access is available on the Agency and Enterprise plans. On other plans, team endpoints return 403 plan_required (“Team access is available on Agency and Enterprise plans.”). (The plan enum value for Agency is pro.)
• Team endpoints use a user session, not an API key. Send Authorization: Bearer <jwt>. Calling them with an X-API-Key is rejected.
• Only members with can_manage_members (owner or admin) can invite, update, or remove teammates.

The four roles

• owner — full control, including billing. Every organization has an owner. The owner role cannot be handed out by invitation.
• admin — manages members, API keys, and integrations, and can publish and delete content, but cannot manage billing.
• operator — can publish and view reports. Cannot manage members, keys, integrations, or delete content.
• client — read and report only. Blocked from team-management views. Useful for giving a customer visibility without edit rights.

Permission matrix

Permission	owner	admin	operator	client
Manage members	Yes	Yes	No	No
Manage billing	Yes	No	No	No
Manage API keys	Yes	Yes	No	No
Manage integrations	Yes	Yes	No	No
Publish pins	Yes	Yes	Yes	No
Delete content (pins/schedules)	Yes	Yes	No	No
Delete assets	Yes	Yes	No	No
Reset sandbox	Yes	Yes	No	No
View reports	Yes	Yes	Yes	Yes

Note that managing billing is owner-only, and deleting content is admin-level (operators can publish but not delete).

Invitation flow

Invitations are token based. The lifecycle is:

1. An owner or admin creates an invitation for an email address and a role.
2. The invited person receives a link carrying the token and accepts it.
3. The invitation status moves through pending → accepted (or expired / revoked).

Invitations expire after a configured window. You can resend or revoke a pending one.

Endpoints (/v1/team/*)

Action	Endpoint
List members	GET /v1/team/members
Update a member’s role	PATCH /v1/team/members/{member_id}
Remove a member	DELETE /v1/team/members/{member_id}
List invitations	GET /v1/team/invitations
Create an invitation	POST /v1/team/invitations
Preview an invitation	GET /v1/team/invitations/preview
Accept an invitation	POST /v1/team/invitations/accept
Resend an invitation	POST /v1/team/invitations/{invitation_id}/resend
Revoke an invitation	DELETE /v1/team/invitations/{invitation_id}

Invite a teammate (curl)

curl -X POST https://api.pinbridge.io/v1/team/invitations \
  -H "Authorization: Bearer $PINBRIDGE_JWT" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "role": "operator"}'

Expected response (trimmed):

{"id": "b6e0a4d8-2f7c-4b3e-9d1a-5c7f3e9b1d42", "email": "[email protected]", "role": "operator", "status": "pending"}

Valid role values are admin, operator, and client. You cannot invite someone as owner (that returns 422), and you cannot invite an unsupported role.

List members (curl)

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

Expected response (trimmed):

[
  {"member_id": "a1d5f9c3-6e2b-4a7d-8c4f-3b9e1d5a7f06", "email": "[email protected]", "role": "owner"},
  {"member_id": "f8c2e6a4-3d9b-4f1c-a7e5-9a4d2c8f6b31", "email": "[email protected]", "role": "operator"}
]

Change a member’s role (curl)

curl -X PATCH https://api.pinbridge.io/v1/team/members/f8c2e6a4-3d9b-4f1c-a7e5-9a4d2c8f6b31 \
  -H "Authorization: Bearer $PINBRIDGE_JWT" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

Python SDK

The SDK exposes team management under client.team. Authenticate with a bearer token, since team endpoints require a user session.

from pinbridge_sdk import PinbridgeClient
from pinbridge_sdk.models import TeamInvitationCreateRequest

with PinbridgeClient(bearer_token="eyJ...") as client:
    client.team.create_invitation(
        TeamInvitationCreateRequest(email="[email protected]", role="operator")
    )

    for member in client.team.list_members():
        print(member["email"], member["role"])

Other methods: list_invitations, resend_invitation(id), revoke_invitation(id), update_member(...), remove_member(id), preview_invitation(token), and accept_invitation(...).

Common errors

Status	Code / message	Cause
403	plan_required	Team access needs the Agency or Enterprise plan.
403	insufficient_permissions (can_manage_members)	The caller is not an owner or admin.
409	“You are already part of this organization.”	Self-invite.
409	“That user is already a member of this organization.”	The invitee is already a member.
409	“An active invitation already exists for that email.”	Duplicate pending invite.
422	“Owner role cannot be assigned by invitation”	Tried to invite an owner.

Next steps

• Managing multiple Pinterest accounts — consolidate agency clients under one project.
• Activity logs — see which teammate did what.
• Retries and failures — how operators handle failed pins.