Organization CRUD Operations

Create, list, retrieve, update, and delete organizations.

Overview

Organizations are the core tenant entities in AuthOS. Each organization:

Has a unique slug identifier
Starts in pending status requiring Platform Owner approval
Has one owner and multiple admins/members
Contains services, settings, and end-users

Status Lifecycle:

pending → active (approved) → suspended (if needed)
        → rejected (if denied)

Endpoints

Method	Path	Description	Permissions
`POST`	`/api/organizations`	Create organization	Authenticated
`GET`	`/api/organizations`	List user’s orgs	Authenticated
`GET`	`/api/organizations/:slug`	Get org details	Member
`PATCH`	`/api/organizations/:slug`	Update org	Owner/Admin
`DELETE`	`/api/organizations/:slug`	Delete org	Owner

POST /api/organizations

Create a new organization. The authenticated user becomes the owner.

Synopsis

Property	Value
Authentication	Required (JWT)
Initial Status	`pending`

Request Body

Field	Type	Required	Description
`slug`	`string`	Yes	Unique URL-friendly identifier
`name`	`string`	Yes	Display name

Validation

Field	Requirements
`slug`	3-50 chars, alphanumeric/hyphens/underscores
`name`	2-100 chars
Reserved slugs	`api`, `auth`, `admin`, `platform`, `docs`, `www`, `mail`

Example Request

curl -X POST https://sso.example.com/api/organizations \
  -H "Authorization: Bearer {jwt}" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "acme-corp",
    "name": "Acme Corporation"
  }'

Response (200 OK)

{
  "organization": {
    "id": "org-uuid",
    "slug": "acme-corp",
    "name": "Acme Corporation",
    "owner_user_id": "user-uuid",
    "status": "pending",
    "tier_id": "free-tier-uuid",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  },
  "membership": {
    "id": "membership-uuid",
    "role": "owner"
  },
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "refresh-token-uuid"
}

Notes

Response includes tokens with organization context
Organization requires Platform Owner approval to become active
Free tier is automatically assigned

GET /api/organizations

List organizations where user is a member.

Synopsis

Property	Value
Authentication	Required (JWT)
Pagination	Yes

Query Parameters

Parameter	Type	Default	Description
`page`	`integer`	1	Page number
`limit`	`integer`	20	Items per page (max 100)
`status`	`string`	-	Filter: `pending`, `active`, `suspended`

Example Request

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

Response (200 OK)

[
  {
    "organization": {
      "id": "org-uuid",
      "slug": "acme-corp",
      "name": "Acme Corporation",
      "status": "active"
    },
    "membership_count": 5,
    "service_count": 3,
    "tier": {
      "name": "Pro",
      "default_max_services": 10
    }
  }
]

GET /api/organizations/:slug

Get organization details.

Synopsis

Property	Value
Authentication	Required (JWT)
Authorization	Organization Member

Path Parameters

Parameter	Type	Description
`slug`	`string`	Organization slug

Example Request

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

Response (200 OK)

{
  "organization": {
    "id": "org-uuid",
    "slug": "acme-corp",
    "name": "Acme Corporation",
    "owner_user_id": "user-uuid",
    "status": "active",
    "tier_id": "tier-uuid",
    "max_services": 10,
    "max_users": 100
  },
  "membership_count": 5,
  "service_count": 3,
  "tier": {
    "name": "Pro"
  }
}

PATCH /api/organizations/:slug

Update organization details.

Synopsis

Property	Value
Authentication	Required (JWT)
Authorization	Owner or Admin

Request Body

Field	Type	Required	Description
`name`	`string`	No	New display name

Example Request

curl -X PATCH https://sso.example.com/api/organizations/acme-corp \
  -H "Authorization: Bearer {jwt}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp International"}'

DELETE /api/organizations/:slug

Delete organization and all associated data.

Synopsis

Property	Value
Authentication	Required (JWT)
Authorization	Owner only
Destructive	Yes

[!CAUTION] This permanently deletes the organization, all services, members, and end-user data.

Example Request

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

Response (200 OK)

{
  "message": "Organization deleted successfully"
}

Organization Data Model

{
  "id": "uuid",
  "slug": "unique-url-identifier",
  "name": "Display Name",
  "owner_user_id": "uuid",
  "status": "pending | active | suspended | rejected",
  "tier_id": "uuid",
  "max_services": 10,
  "max_users": 100,
  "custom_domain": "auth.example.com",
  "domain_verified": true,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}