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

# Tenant Management

The co-mind.ai platform supports multi-tenant isolation. Each tenant has its own users, API keys, usage quotas, and sub-organizations.

<Note>
  All tenant management endpoints require **JWT authentication** with **Admin** or **System Admin** role.
</Note>

## Tenants

### Tenant CRUD

| Endpoint                       | Method | Auth     | Purpose                     |
| ------------------------------ | ------ | -------- | --------------------------- |
| `/v1/admin/tenants`            | GET    | Admin    | List all tenants            |
| `/v1/admin/tenants`            | POST   | SysAdmin | Create a new tenant         |
| `/v1/admin/tenants/{id}`       | GET    | Admin    | Get tenant details          |
| `/v1/admin/tenants/{id}`       | PATCH  | Admin    | Update tenant settings      |
| `/v1/admin/tenants/{id}`       | DELETE | SysAdmin | Delete tenant               |
| `/v1/admin/tenants/{id}/usage` | GET    | Admin    | Get tenant usage statistics |

### Create a Tenant

```bash theme={null}
curl -X POST https://your-instance/v1/admin/tenants \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "plan": "enterprise"
  }'
```

### Get Tenant Usage

```bash theme={null}
curl https://your-instance/v1/admin/tenants/TENANT_ID/usage \
  -H "Authorization: Bearer $JWT"
```

## User Management

| Endpoint                                | Method | Purpose                      |
| --------------------------------------- | ------ | ---------------------------- |
| `/v1/admin/tenants/{id}/users`          | GET    | List tenant users            |
| `/v1/admin/tenants/{id}/users`          | POST   | Add user to tenant           |
| `/v1/admin/tenants/{id}/users/{userId}` | PATCH  | Update user role             |
| `/v1/admin/tenants/{id}/users/{userId}` | DELETE | Remove user from tenant      |
| `/v1/admin/users/create`                | POST   | Create user with credentials |

### Add User to Tenant

```bash theme={null}
curl -X POST https://your-instance/v1/admin/tenants/TENANT_ID/users \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "role": "member"
  }'
```

### Update User Role

```bash theme={null}
curl -X PATCH https://your-instance/v1/admin/tenants/TENANT_ID/users/USER_ID \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'
```

### Create User with Credentials

```bash theme={null}
curl -X POST https://your-instance/v1/admin/users/create \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "password": "secure_password",
    "name": "New User",
    "role": "member"
  }'
```

## Tenant API Keys

Manage provider-level API keys for a tenant (e.g., OpenAI, Anthropic keys that the platform uses to call external providers).

| Endpoint                                  | Method | Purpose                 |
| ----------------------------------------- | ------ | ----------------------- |
| `/v1/admin/tenants/{id}/api-keys`         | GET    | List provider API keys  |
| `/v1/admin/tenants/{id}/api-keys`         | POST   | Create provider API key |
| `/v1/admin/tenants/{id}/api-keys/{keyId}` | DELETE | Delete provider API key |

### Create Provider API Key

```bash theme={null}
curl -X POST https://your-instance/v1/admin/tenants/TENANT_ID/api-keys \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "key": "sk-..."
  }'
```

## Sub-Organizations

Sub-organizations provide an additional layer of isolation within a tenant — useful for departments, teams, or business units.

| Endpoint                                           | Method | Purpose                 |
| -------------------------------------------------- | ------ | ----------------------- |
| `/v1/admin/tenants/{tenantId}/sub-orgs`            | GET    | List sub-organizations  |
| `/v1/admin/tenants/{tenantId}/sub-orgs`            | POST   | Create sub-organization |
| `/v1/admin/tenants/{tenantId}/sub-orgs/{subOrgId}` | GET    | Get sub-org details     |
| `/v1/admin/tenants/{tenantId}/sub-orgs/{subOrgId}` | PATCH  | Update sub-org          |
| `/v1/admin/tenants/{tenantId}/sub-orgs/{subOrgId}` | DELETE | Delete sub-org          |

### Create Sub-Organization

```bash theme={null}
curl -X POST https://your-instance/v1/admin/tenants/TENANT_ID/sub-orgs \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering",
    "description": "Engineering department"
  }'
```