Team

Change the role, brand access, or API access of a colleague (preview, then confirm)

API access: send api_access (true or false) on its own to let this teammate use the workspace API plan from their own keys and AI apps, or to stop it. Off by default. The owner or an admin changes it for someone else, never for themselves (403 cannot_change_own_access); only the owner changes it for an admin. Turning it off stops their keys and AI app connections in this workspace on the next request and switches off their webhooks for it. The workspace owner is emailed. Owner or admin. Same rules as the dashboard: nobody changes their own role, only the owner changes an admin seat, the owner seat never changes. Admin cannot be granted over the API. Moving a seat to admin is dashboard-only; brands are ignored for admins, who see every brand. Two steps. Without confirm: true the call returns 200 with requires_confirmation, a plain-language preview and a short-lived preview_id, and changes nothing. Show the preview to the user; after they approve, repeat the call with confirm: true and the preview_id. If anything changed in between, the confirm answers 409 preview_stale and changes nothing (a safeguard for the user, not a security control: every rule is checked again on confirm). Access: an API key that a person granted "Manage team" in /dashboard/api (members:read and members:write). Browser sessions are refused with api_key_required; the scopes can never be requested through POST /api/v1/api-keys. ChatGPT, Claude and other OAuth connections hold both scopes implicitly (when their grant includes accounts:write) but may call this endpoint only while the person is an owner or admin of the workspace; otherwise 403 team_management_requires_admin. A key bound to another workspace, or a caller who is not a member, gets 404; a caller whose seat was removed gets 403 workspace_access_revoked. Limit: 30 role, brand, removal and revoke requests per workspace per 24 hours (previews count).

patch/api/v1/workspaces/{workspaceId}/members/{memberId}

Request

  • Base URL: https://www.poster.ly
  • URL: https://www.poster.ly/api/v1/workspaces/{workspaceId}/members/{memberId}
  • Auth: HTTP bearer

Path parameters

workspaceIdstring uuid required

Workspace ID (from whoami).

memberIdstring uuid required

Member ID from GET /api/v1/workspaces/{workspaceId}/members.

Request body

role'publisher' | 'editor' | 'viewer'
brand_idsstring[]

Replaces the brand limit. Empty means every brand. Omit to keep the current brands.

api_accessboolean

Members only, in its own request. true lets the teammate use this workspace API plan from their own keys and AI apps; false turns it off, which also switches off their webhooks for this workspace. You cannot change your own (403 cannot_change_own_access); the owner row answers 403 owner_api_access_fixed.

confirmboolean
preview_idstring

Example request

{
  "role": "viewer"
}

Response

Preview (nothing changed) or the updated member.

OR

Example response

{
  "requires_confirmation": true,
  "preview": {
    "action": "invite",
    "summary": "Send an invite email to sam@agency.com to join the workspace as Editor. It counts toward your 10 seats (4 in use now).",
    "email": "sam@agency.com",
    "role": "editor",
    "previous_role": null,
    "brand_ids": [],
    "previous_brand_ids": null,
    "sends_email": true,
    "counts_toward_seats": true,
    "seats_used": 4,
    "seat_limit": 10
  },
  "preview_id": "mp1.1790000900000.q3v9...",
  "preview_expires_at": "2026-09-23T12:15:00.000Z",
  "next_step": "Nothing has changed yet. Show this preview to the user and, only after they explicitly approve, call again with confirm: true and this preview_id."
}

Changes

No recorded changes to this operation across all 1 revision of this API.