Create Organization

Team administrator can create a new organization along with an initial workspace and user account.

Quick Navigation

• Endpoint
• Headers
• Request Body
• Response
• Success (201)
• Features

Outline

• Endpoint
• Headers
• Request Body
• Response
  • Success (201)
• Features

Endpoint

POST /api/v1/organizations

Headers

Header	Required	Description
Content-Type	Yes	application/json

Request Body

{
  "name": "Acme Corporation",
  "domain": "acme.com",
  "workspace_name": "Main Workspace",
  "admin_email": "admin@acme.com",
  "admin_password": "SecurePassword123!",
  "admin_display_name": "Admin User",
  "idempotency_key": "unique_key_123"
}

Response

Success (201)

{
  "success": true,
  "data": {
    "organization": {
      "id": 1,
      "name": "Acme Corporation",
      "domain": "acme.com",
      "plan": "enterprise"
    },
    "workspace": {
      "id": 1,
      "name": "Main Workspace",
      "slug": "main-workspace"
    },
    "user": {
      "id": 123,
      "email": "admin@acme.com",
      "display_name": "Admin User"
    },
    "message": "Organization created successfully"
  },
  "message": "Organization created successfully"
}

Features

• Automatic user account creation if not exists
• Password strength validation
• Rate limiting (3 attempts per 5 minutes)
• Idempotency key support
• Audit logging
• Email verification queued if user is new
• Create organization and default workspace (customizable name)
• Create default roles (Admin, Developer, Viewer)
• Assign Admin role to the user
• Optionally apply organization settings during creation
• Optionally invite additional members to the initial workspace