> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin API

> Platform-level tenant management (platform:admin scope required)

<Warning>
  These endpoints require the `platform:admin` scope. They are intended for MeshAI platform operators, not regular tenants.
</Warning>

## List Tenants

```
GET /admin/tenants
```

List all tenants on the platform.

| Parameter | Type    | Description                                                                |
| --------- | ------- | -------------------------------------------------------------------------- |
| `plan`    | string  | Filter by plan: `starter`, `professional`, `enterprise`, `enterprise_plus` |
| `page`    | integer | Page number                                                                |
| `limit`   | integer | Results per page                                                           |

```bash theme={null}
curl https://api.meshai.dev/api/v1/admin/tenants \
  -H "Authorization: Bearer msh_PLATFORM_ADMIN_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "tnt_abc123",
        "company_name": "Acme Corp",
        "plan": "professional",
        "active_agents": 47,
        "agent_limit": 100,
        "owner_email": "admin@acme.com",
        "monthly_cost_usd": 799.00,
        "created_at": "2026-01-15T08:00:00Z",
        "last_activity": "2026-03-17T10:30:00Z"
      },
      {
        "id": "tnt_def456",
        "company_name": "Globex Inc",
        "plan": "enterprise",
        "active_agents": 234,
        "agent_limit": 1000,
        "owner_email": "admin@globex.com",
        "monthly_cost_usd": 1999.00,
        "created_at": "2026-02-01T08:00:00Z",
        "last_activity": "2026-03-17T09:15:00Z"
      }
    ],
    "meta": { "total": 42, "page": 1, "limit": 20 }
  }
  ```
</ResponseExample>

## Create a Tenant

```
POST /admin/tenants
```

Provision a new tenant (e.g., for enterprise onboarding or testing).

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/admin/tenants \
  -H "Authorization: Bearer msh_PLATFORM_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "NewCo Ltd",
    "owner_email": "admin@newco.com",
    "plan": "enterprise",
    "agent_limit": 500
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "tnt_ghi789",
      "company_name": "NewCo Ltd",
      "plan": "enterprise",
      "agent_limit": 500,
      "owner_email": "admin@newco.com",
      "api_key": "msh_live_newco_abc123",
      "created_at": "2026-03-17T10:00:00Z"
    }
  }
  ```
</ResponseExample>

<Warning>
  The API key is shown once at creation time. Share it securely with the tenant admin.
</Warning>

## Delete a Tenant

```
DELETE /admin/tenants/{tenant_id}
```

Permanently delete a tenant and all associated data (agents, policies, audit events, billing).

```bash theme={null}
curl -X DELETE https://api.meshai.dev/api/v1/admin/tenants/tnt_abc123 \
  -H "Authorization: Bearer msh_PLATFORM_ADMIN_KEY"
```

Returns `204 No Content` on success.

<Warning>
  This action is irreversible. All tenant data is permanently deleted. Use with extreme caution.
</Warning>