Skip to main content

​
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) 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

ParameterTypeRequiredDescription
namestringYesName for the new organization
tenant_namestringYesDisplay name for the tenant
hdarray of stringsYesApproved email domains for the organization (e.g., ["europe.acme.com"])
logo_urlstringNoURL 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

ParameterTypeRequiredDescription
organization_idstring (UUID)YesID 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

StatusMeaningSolution
401Invalid API keyVerify your API key is correct
403Insufficient permissionsEnsure API key owner has Admin role
404Organization not foundVerify the organization ID exists
422Invalid requestCheck request body and organization name
500Server errorRetry with exponential backoff

​
Next steps

Invite users

Add team members to your organizations

API overview

Learn about API authentication and best practices