Admin Organizations API

Manage organizations across the platform with administrative privileges. These endpoints allow you to list, create, update, and delete organizations.

Base URL

/api/admin/organizations

Authentication

Required: Admin role

Authorization: Bearer <admin_session_token>

Endpoints

List Organizations

Retrieve a paginated list of all organizations in the system.

GET /api/admin/organizations

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Items per page (max 100)
`search`	string	-	Search by name or slug
`plan`	string	-	Filter by subscription plan
`status`	string	-	Filter by status (active, suspended, pending)

Response

{
  "success": true,
  "data": [
    {
      "id": "org_789",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "plan": "enterprise",
      "status": "active",
      "memberCount": 25,
      "ownerId": "user_123456",
      "createdAt": "2023-06-15T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3
  }
}

Get Organization

Retrieve detailed information about a specific organization.

GET /api/admin/organizations/:id

Response

{
  "success": true,
  "data": {
    "id": "org_789",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "description": "Leading provider of example products",
    "plan": "enterprise",
    "status": "active",
    "ownerId": "user_123456",
    "owner": {
      "id": "user_123456",
      "email": "owner@acme.com",
      "name": "John Owner"
    },
    "members": [
      {
        "id": "user_123456",
        "email": "owner@acme.com",
        "name": "John Owner",
        "role": "owner"
      },
      {
        "id": "user_789012",
        "email": "member@acme.com",
        "name": "Jane Member",
        "role": "member"
      }
    ],
    "settings": {
      "allowPublicProjects": true,
      "maxProjects": 50,
      "maxTeamMembers": 25
    },
    "billing": {
      "stripeCustomerId": "cus_abc123",
      "subscriptionId": "sub_xyz789",
      "currentPeriodEnd": "2024-03-01T00:00:00Z"
    },
    "metadata": {
      "industry": "technology",
      "size": "50-100"
    },
    "createdAt": "2023-06-15T10:30:00Z",
    "updatedAt": "2024-01-20T08:15:00Z"
  }
}

Create Organization

Create a new organization.

POST /api/admin/organizations

Request Body

{
  "name": "New Organization",
  "slug": "new-org",
  "description": "A new organization",
  "plan": "pro",
  "ownerId": "user_123456",
  "settings": {
    "maxProjects": 25,
    "maxTeamMembers": 10
  }
}

Request Fields

Field	Type	Required	Description
`name`	string	Yes	Organization name
`slug`	string	Yes	URL-friendly identifier
`description`	string	No	Organization description
`plan`	string	No	Subscription plan (default: `free`)
`ownerId`	string	Yes	User ID to set as organization owner
`settings`	object	No	Organization-specific settings

Response

{
  "success": true,
  "data": {
    "id": "org_456",
    "name": "New Organization",
    "slug": "new-org",
    "plan": "pro",
    "status": "active",
    "ownerId": "user_123456",
    "createdAt": "2024-02-04T10:00:00Z"
  }
}

Update Organization

Update an existing organization's information.

PATCH /api/admin/organizations/:id

Request Body

{
  "name": "Updated Organization Name",
  "plan": "enterprise",
  "settings": {
    "maxProjects": 100,
    "allowPublicProjects": false
  }
}

Response

{
  "success": true,
  "data": {
    "id": "org_456",
    "name": "Updated Organization Name",
    "slug": "new-org",
    "plan": "enterprise",
    "settings": {
      "maxProjects": 100,
      "allowPublicProjects": false
    },
    "updatedAt": "2024-02-04T11:30:00Z"
  }
}

Delete Organization

Permanently delete an organization and optionally its data.

DELETE /api/admin/organizations/:id

Query Parameters

Parameter	Type	Default	Description
`transferMembersTo`	string	-	Organization ID to transfer members to
`deleteData`	boolean	false	Permanently delete all organization data

Response

{
  "success": true,
  "data": {
    "message": "Organization deleted successfully",
    "deletedAt": "2024-02-04T12:00:00Z"
  }
}

List Organization Members

Get all members of a specific organization.

GET /api/admin/organizations/:id/members

Response

{
  "success": true,
  "data": [
    {
      "id": "user_123456",
      "email": "owner@acme.com",
      "name": "John Owner",
      "role": "owner",
      "joinedAt": "2023-06-15T10:30:00Z"
    },
    {
      "id": "user_789012",
      "email": "member@acme.com",
      "name": "Jane Member",
      "role": "member",
      "joinedAt": "2023-07-01T09:00:00Z"
    }
  ]
}

Add Organization Member

Add a user to an organization.

POST /api/admin/organizations/:id/members

Request Body

{
  "userId": "user_999999",
  "role": "member"
}

Response

{
  "success": true,
  "data": {
    "id": "user_999999",
    "email": "newmember@example.com",
    "name": "New Member",
    "role": "member",
    "joinedAt": "2024-02-04T12:00:00Z"
  }
}

Remove Organization Member

Remove a user from an organization.

DELETE /api/admin/organizations/:id/members/:userId

Response

{
  "success": true,
  "data": {
    "message": "Member removed successfully",
    "removedAt": "2024-02-04T12:00:00Z"
  }
}

Update Member Role

Change a member's role within an organization.

PATCH /api/admin/organizations/:id/members/:userId

Request Body

{
  "role": "admin"
}

Response

{
  "success": true,
  "data": {
    "id": "user_789012",
    "email": "member@acme.com",
    "name": "Jane Member",
    "role": "admin",
    "updatedAt": "2024-02-04T12:00:00Z"
  }
}

Suspend Organization

Temporarily suspend an organization.

POST /api/admin/organizations/:id/suspend

Request Body

{
  "reason": "Payment overdue",
  "duration": "30d"
}

Response

{
  "success": true,
  "data": {
    "id": "org_789",
    "status": "suspended",
    "suspendedUntil": "2024-03-05T12:00:00Z",
    "suspensionReason": "Payment overdue"
  }
}

Error Codes

Code	Description
`ORGANIZATION_NOT_FOUND`	The specified organization does not exist
`SLUG_ALREADY_EXISTS`	Organization slug is already in use
`INVALID_OWNER`	Owner user ID is invalid or not found
`CANNOT_DELETE_DEFAULT`	Cannot delete the default organization
`MEMBER_NOT_FOUND`	User is not a member of this organization
`CANNOT_REMOVE_OWNER`	Cannot remove the organization owner

SDK Example

import { createAdminClient } from '@/lib/admin/client';

const admin = createAdminClient();

// List organizations
const orgs = await admin.organizations.list({
  plan: 'enterprise',
  status: 'active',
  page: 1,
  limit: 50
});

// Create new organization
const newOrg = await admin.organizations.create({
  name: 'Tech Startup Inc',
  slug: 'tech-startup',
  plan: 'pro',
  ownerId: 'user_123456'
});

// Get organization details
const org = await admin.organizations.get('org_789');

// Update organization plan
await admin.organizations.update('org_789', {
  plan: 'enterprise',
  settings: {
    maxProjects: 100,
    maxTeamMembers: 50
  }
});

// Add member to organization
await admin.organizations.addMember('org_789', {
  userId: 'user_999999',
  role: 'member'
});

// List organization members
const members = await admin.organizations.listMembers('org_789');

Admin Organizations API

On this page