Organization Governance

Platform owner endpoints for managing organization lifecycle.

Overview

Platform owners control which organizations can use the platform:

Action	Description
Approve	Activates pending organization
Reject	Denies pending organization with reason
Suspend	Temporarily disables active organization
Activate	Re-enables suspended organization
Delete	Permanently removes organization

Endpoints

Method	Path	Description
`GET`	`/api/platform/tiers`	List tiers
`GET`	`/api/platform/organizations`	List all orgs
`POST`	`/api/platform/organizations/:id/approve`	Approve org
`POST`	`/api/platform/organizations/:id/reject`	Reject org
`POST`	`/api/platform/organizations/:id/suspend`	Suspend org
`POST`	`/api/platform/organizations/:id/activate`	Reactivate org
`PATCH`	`/api/platform/organizations/:id/tier`	Change tier
`DELETE`	`/api/platform/organizations/:id`	Delete org

GET /api/platform/tiers

List available organization tiers.

Response (200 OK)

[
  {
    "id": "tier_free",
    "name": "free",
    "display_name": "Free Tier",
    "default_max_services": 3,
    "default_max_users": 100,
    "price_cents": 0
  },
  {
    "id": "tier_pro",
    "name": "pro",
    "display_name": "Professional",
    "default_max_services": 10,
    "default_max_users": 1000,
    "price_cents": 9900
  }
]

GET /api/platform/organizations

List all organizations with filtering.

Query Parameters

Parameter	Type	Description
`status`	`string`	`pending`, `active`, `suspended`, `rejected`
`tier_id`	`string`	Filter by tier
`limit`	`integer`	Max results (default: 50)
`offset`	`integer`	Pagination offset

Example Request

curl -X GET "https://sso.example.com/api/platform/organizations?status=pending" \
  -H "Authorization: Bearer {platform_owner_jwt}"

Response (200 OK)

{
  "organizations": [
    {
      "organization": {
        "id": "org-uuid",
        "slug": "acme-corp",
        "name": "Acme Corporation",
        "status": "active",
        "tier_id": "tier_pro",
        "created_at": "2025-01-15T10:30:00Z"
      },
      "owner": {
        "id": "user-uuid",
        "email": "owner@acme.com",
        "is_platform_owner": false,
        "created_at": "2025-01-10T08:00:00Z"
      },
      "tier": {
        "id": "tier_pro",
        "name": "pro",
        "display_name": "Professional"
      }
    }
  ],
  "total": 42
}

[!NOTE] If an organization’s owner user has been deleted, the owner fields will contain fallback values:

owner.id: "unknown"

owner.email: "deleted-user@unknown"

owner.is_platform_owner: false

owner.created_at: "1970-01-01T00:00:00Z"

POST /api/platform/organizations/:id/approve

Approve a pending organization.

Request Body

Field	Type	Required	Description
`tier_id`	`string`	No	Tier to assign (default: free)

Example Request

curl -X POST https://sso.example.com/api/platform/organizations/org-uuid/approve \
  -H "Authorization: Bearer {platform_owner_jwt}" \
  -H "Content-Type: application/json" \
  -d '{"tier_id": "tier_pro"}'

Response (200 OK)

{
  "organization": {
    "id": "org-uuid",
    "status": "active",
    "approved_at": "2025-01-15T10:30:00Z"
  }
}

POST /api/platform/organizations/:id/reject

Reject a pending organization.

Request Body

Field	Type	Required	Description
`reason`	`string`	Yes	Rejection reason

Example Request

curl -X POST https://sso.example.com/api/platform/organizations/org-uuid/reject \
  -H "Authorization: Bearer {platform_owner_jwt}" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Insufficient information provided"}'

POST /api/platform/organizations/:id/suspend

Suspend an active organization.

Request Body

Field	Type	Required	Description
`reason`	`string`	No	Suspension reason

POST /api/platform/organizations/:id/activate

Reactivate a suspended organization.

PATCH /api/platform/organizations/:id/tier

Update organization tier.

Request Body

Field	Type	Required	Description
`tier_id`	`string`	Yes	New tier ID
`max_services`	`integer`	No	Custom service limit
`max_users`	`integer`	No	Custom user limit

DELETE /api/platform/organizations/:id

Permanently delete an organization.

[!CAUTION] This permanently deletes the organization and all associated data.