Organization Management API: Multi-Tenant Wolfia

Overview

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) Creates a new child organization under your parent organization and switches the current session to it.

Request

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)

{
  "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

curl -X GET https://api.wolfia.com/v1/organizations/tenant/list \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"

Response (200 OK)

[
  {
    "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
  }
]

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

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

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)

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

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.

Integration example

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

API

Organization Management API: Multi-Tenant Wolfia

Overview

Create a child organization

Request

Request body

Response (200 OK)

List organizations

Request

Response (200 OK)

Switch organization

Request

Request body

Response (200 OK)

Integration example

Error responses

Next steps

Invite users

API overview

​Overview

​Create a child organization

​Request

​Request body

​Response (200 OK)

​List organizations

​Request

​Response (200 OK)

​Switch organization

​Request

​Request body

​Response (200 OK)

​Integration example

​Error responses

​Next steps

Invite users

API overview

Overview

Create a child organization

Request

Request body

Response (200 OK)

List organizations

Request

Response (200 OK)

Switch organization

Request

Request body

Response (200 OK)

Integration example

Error responses

Next steps