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

# Organization Management API: Multi-Tenant Wolfia

> Create and manage multi-tenant organizations via the Wolfia API: child orgs, listing, and switching, for MSPs, consultancies, and multi-BU enterprises.

## Overview

Manage multi-tenant organizations programmatically. Create child organizations, list available organizations, and switch between them.

Useful for managed service providers, consulting firms, or enterprises with multiple business units that each need their own isolated Wolfia workspace.

All endpoints require Admin role authentication.

## Create a child organization

**URL:** `POST https://api.wolfia.com/v1/organizations/tenant/create`

**Authentication:** API key required, Admin role (see [API overview](/how-to/api-overview))

Creates a new child organization under your parent organization and switches the current session to it.

### Request

```bash theme={null}
curl -X POST https://api.wolfia.com/v1/organizations/tenant/create \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME Europe Division",
    "tenant_name": "ACME Europe Division",
    "hd": ["europe.acme.com"],
    "logo_url": "https://example.com/logo-europe.png"
  }'
```

### Request body

| Parameter     | Type             | Required | Description                                                               |
| ------------- | ---------------- | -------- | ------------------------------------------------------------------------- |
| `name`        | string           | Yes      | Name for the new organization                                             |
| `tenant_name` | string           | Yes      | Display name for the tenant                                               |
| `hd`          | array of strings | Yes      | Approved email domains for the organization (e.g., `["europe.acme.com"]`) |
| `logo_url`    | string           | No       | URL to the organization's logo                                            |

### Response (200 OK)

```json theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "ACME Europe Division",
  "tenant_name": "ACME Europe Division",
  "hd": ["europe.acme.com"],
  "logo_url": "https://example.com/logo-europe.png"
}
```

## List organizations

**URL:** `GET https://api.wolfia.com/v1/organizations/tenant/list`

**Authentication:** API key required, Admin role

Returns organizations available for switching. Non-admin users receive an empty list.

### Request

```bash theme={null}
curl -X GET https://api.wolfia.com/v1/organizations/tenant/list \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"
```

### Response (200 OK)

```json theme={null}
[
  {
    "id": "org-uuid-1",
    "name": "ACME Corp",
    "tenant_name": "ACME Corp (Parent)",
    "logo_url": "https://example.com/logo.png"
  },
  {
    "id": "org-uuid-2",
    "name": "ACME Corp",
    "tenant_name": "ACME Europe Division",
    "logo_url": "https://example.com/logo-europe.png"
  },
  {
    "id": "org-uuid-3",
    "name": "ACME Corp",
    "tenant_name": "ACME APAC Division",
    "logo_url": null
  }
]
```

<Note>
  The response includes additional organization metadata fields beyond those shown above, such as `hd` (approved email domains).
</Note>

## Switch organization

**URL:** `POST https://api.wolfia.com/v1/organizations/tenant/switch`

**Authentication:** API key required, Admin role

Switch the current session to a different organization. After switching, all subsequent API calls operate in the context of the target organization.

### Request

```bash theme={null}
curl -X POST https://api.wolfia.com/v1/organizations/tenant/switch \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org-uuid-2"
  }'
```

### Request body

| Parameter         | Type          | Required | Description                         |
| ----------------- | ------------- | -------- | ----------------------------------- |
| `organization_id` | string (UUID) | Yes      | ID of the organization to switch to |

### Response (200 OK)

```json theme={null}
{
  "id": "org-uuid-2",
  "name": "ACME Corp",
  "tenant_name": "ACME Europe Division",
  "logo_url": "https://example.com/logo-europe.png"
}
```

<Note>
  After switching, all API calls using this session will operate in the context of the target organization. Switch back to your parent organization when done.
</Note>

## Integration example

```python theme={null}
import os

import requests

API_KEY = os.environ['WOLFIA_API_KEY']
BASE_URL = 'https://api.wolfia.com/v1'


def create_child_organization(name, tenant_name, hd, logo_url=None):
    """Create a new child organization."""
    headers = {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json',
    }

    payload = {'name': name, 'tenant_name': tenant_name, 'hd': hd}
    if logo_url:
        payload['logo_url'] = logo_url

    response = requests.post(
        f'{BASE_URL}/organizations/tenant/create',
        headers=headers,
        json=payload,
        timeout=30,
    )
    response.raise_for_status()

    org = response.json()
    print(f"Created: {org['tenant_name']} ({org['id']})")
    return org


def list_organizations():
    """List all available organizations."""
    headers = {'X-API-Key': API_KEY}

    response = requests.get(
        f'{BASE_URL}/organizations/tenant/list',
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()

    orgs = response.json()
    print(f"Available organizations ({len(orgs)}):")
    for org in orgs:
        print(f"  - {org['tenant_name']} ({org['id']})")

    return orgs


def switch_organization(org_id):
    """Switch to a different organization."""
    headers = {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json',
    }

    response = requests.post(
        f'{BASE_URL}/organizations/tenant/switch',
        headers=headers,
        json={'organization_id': org_id},
        timeout=30,
    )
    response.raise_for_status()

    org = response.json()
    print(f"Switched to: {org['tenant_name']}")
    return org


if __name__ == '__main__':
    orgs = list_organizations()

    new_org = create_child_organization(
        name="New Regional Office",
        logo_url="https://example.com/regional-logo.png",
    )
```

## Error responses

| Status | Meaning                  | Solution                                 |
| ------ | ------------------------ | ---------------------------------------- |
| 401    | Invalid API key          | Verify your API key is correct           |
| 403    | Insufficient permissions | Ensure API key owner has Admin role      |
| 404    | Organization not found   | Verify the organization ID exists        |
| 422    | Invalid request          | Check request body and organization name |
| 500    | Server error             | Retry with exponential backoff           |

## Next steps

<CardGroup cols={2}>
  <Card title="Invite users" icon="user-plus" href="/how-to/api-invite-users">
    Add team members to your organizations
  </Card>

  <Card title="API overview" icon="code" href="/how-to/api-overview">
    Learn about API authentication and best practices
  </Card>
</CardGroup>