Member Management

Endpoints for managing organization members, roles, and ownership.

Overview

Organizations have three member roles:

Role	Permissions
Owner	Full control, can transfer ownership, delete org
Admin	Manage members, services, settings
Member	View access, use services

Endpoints

Method	Path	Description	Permissions
`GET`	`/api/organizations/:slug/members`	List members	Member
`PATCH`	`/api/organizations/:slug/members/:user_id`	Update role	Owner
`POST`	`/api/organizations/:slug/members/:user_id`	Remove member	Owner/Admin
`POST`	`/api/organizations/:slug/transfer-ownership`	Transfer ownership	Owner
`POST`	`/api/organizations/:slug/select`	Switch to organization	Member

GET /api/organizations/:slug/members

List organization members with pagination.

Synopsis

Property	Value
Authentication	Required (JWT)
Authorization	Organization Member

Query Parameters

Parameter	Type	Default	Description
`page`	`integer`	1	Page number
`limit`	`integer`	50	Items per page (max 100)
`role`	`string`	-	Filter: `owner`, `admin`, `member`

Example Request

curl -X GET "https://sso.example.com/api/organizations/acme-corp/members?role=admin" \
  -H "Authorization: Bearer {jwt}"

Response (200 OK)

{
  "members": [
    {
      "user": {
        "id": "user-uuid",
        "email": "admin@acme.com",
        "is_platform_owner": false
      },
      "membership": {
        "id": "membership-uuid",
        "role": "admin",
        "created_at": "2025-01-15T10:30:00Z"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 5
  },
  "limits": {
    "max_users": 100,
    "source": "Pro Tier"
  }
}

PATCH /api/organizations/:slug/members/:user_id

Update a member’s role.

Synopsis

Property	Value
Authentication	Required (JWT)
Authorization	Owner only

Request Body

Field	Type	Required	Description
`role`	`string`	Yes	New role: `admin` or `member`

Example Request

curl -X PATCH https://sso.example.com/api/organizations/acme-corp/members/user-uuid \
  -H "Authorization: Bearer {jwt}" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

Response (200 OK)

{
  "user": {
    "id": "user-uuid",
    "email": "user@acme.com"
  },
  "membership": {
    "id": "membership-uuid",
    "role": "admin",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Errors

Status	Condition
`400`	Cannot change own role
`400`	Cannot set role to `owner` (use transfer)
`403`	Not the organization owner
`404`	Member not found

POST /api/organizations/:slug/members/:user_id

Remove a member from the organization.

Synopsis

Property	Value
Authentication	Required (JWT)
Authorization	Owner or Admin

Example Request

curl -X POST https://sso.example.com/api/organizations/acme-corp/members/user-uuid \
  -H "Authorization: Bearer {jwt}"

Response (200 OK)

{
  "message": "Member removed successfully"
}

Errors

Status	Condition
`400`	Cannot remove yourself
`400`	Cannot remove the owner
`403`	Insufficient permissions

POST /api/organizations/:slug/transfer-ownership

Transfer organization ownership to another member.

Synopsis

Property	Value
Authentication	Required (JWT)
Authorization	Owner only
Side Effects	Current owner becomes admin

Request Body

Field	Type	Required	Description
`new_owner_user_id`	`string`	Yes	User ID of new owner

Example Request

curl -X POST https://sso.example.com/api/organizations/acme-corp/transfer-ownership \
  -H "Authorization: Bearer {jwt}" \
  -H "Content-Type: application/json" \
  -d '{"new_owner_user_id": "new-owner-uuid"}'

Response (200 OK)

{
  "message": "Ownership transferred successfully",
  "old_owner": {
    "user_id": "old-owner-uuid",
    "new_role": "admin"
  },
  "new_owner": {
    "user_id": "new-owner-uuid",
    "role": "owner"
  }
}

Notes

New owner must already be a member
Current owner is demoted to admin
Triggers organization.owner.changed webhook

POST /api/organizations/:slug/select

Switch the current session’s organization context.

Synopsis

Property	Value
Authentication	Required (JWT)
Authorization	Organization Member
Returns	New tokens

Example Request

curl -X POST https://sso.example.com/api/organizations/acme-corp/select \
  -H "Authorization: Bearer {jwt}"

Response (200 OK)

{
  "user": {
    "id": "user-uuid",
    "email": "user@acme.com"
  },
  "membership": {
    "id": "membership-uuid",
    "role": "admin"
  },
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "new-refresh-token"
}

The new tokens have the org claim set to the selected organization.

Membership Model

{
  "id": "uuid",
  "org_id": "uuid",
  "user_id": "uuid",
  "role": "owner | admin | member",
  "created_at": "2025-01-15T10:30:00Z"
}