Memberships API

Membership APIs control who has which role on an account or workspace. All writes update Postgres and SpiceDB atomically (DLQ on SpiceDB failure).

List members

GET /v1/scopes/{scope_type}/{scope_id}/members

Path param	Values
`scope_type`	`account` or `workspace`
`scope_id`	Account or workspace UUID

Permission: read on scope

curl -s -H "Authorization: Bearer $TOKEN" \
  "$CP_URL/v1/scopes/workspace/$WORKSPACE_ID/members" | jq .

Response `200`

{
  "memberships": [
    {
      "id": "…",
      "user_id": "…",
      "scope_type": "workspace",
      "scope_id": "…",
      "role": "admin",
      "user_email": "admin@example.com",
      "user_display_name": "Admin User",
      "created_at": "2026-05-01T12:00:00Z"
    }
  ]
}

Add member

POST /v1/scopes/{scope_type}/{scope_id}/members

Permission: manage_members on scope

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"<portal_user_uuid>","role":"writer"}' \
  "$CP_URL/v1/scopes/workspace/$WORKSPACE_ID/members" | jq .

Request body

Field	Type	Required	Description
`user_id`	uuid	One of	Existing Portal user ID
`email`	string	One of	Invite by email (provisions Keycloak user)
`role`	enum	Yes	`owner`, `admin`, `writer`, `member`, `partner`, `billing_admin`
`expires_at`	string	No	ISO-8601 expiry

Provide exactly one of user_id or email.

billing_admin is valid on account scope only.

Revoke membership

DELETE /v1/memberships/{membership_id}

Permission: manage_members on the membership's scope

curl -s -X DELETE -H "Authorization: Bearer $TOKEN" \
  "$CP_URL/v1/memberships/$MEMBERSHIP_ID" -w "%{http_code}\n"

Returns 204 No Content on success.

Roles vs permissions

Role names are stored on the membership row. Effective permissions are enforced via SpiceDB relationships and the closed action vocabulary — see Core concepts.

Errors

Status	Meaning
400	Invalid `scope_type` or both `user_id` and `email` provided
403	Missing `manage_members`
404	Membership or user not found