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
| 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 |
Next steps
