Organization CRUD

Create, read, update, and delete organizations

AuthOS release 0.8.5 API v1 Latest-only documentation
Updated Jul 15, 2026
On this page

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, www, mail, ftp, admin, root, support, help, docs, blog, news, status, health, ping, cdn, assets, static

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"
  },
  "owner": {
    "id": "user-uuid",
    "email": "user@example.com"
  },
  "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"
}