Organization Management Examples¶

Last Updated: 2025-11-23

Complete examples for managing organizations, members, and organization settings in the multi-tenant environment.

Table of Contents¶

Create Organization
List Organizations
Get Organization Details
Update Organization
Delete Organization
Add Members
List Organization Members
Update Member Role
Remove Member
Set Primary Organization

Create Organization¶

Create a new organization. The creating user becomes the organization owner with admin role.

REST API¶

Endpoint: POST /api/v1/organizations

curl Example¶

curl -X POST http://localhost:8080/api/v1/organizations \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME Corporation",
    "slug": "acme-corp",
    "settings": "{\"theme\": \"dark\", \"timezone\": \"UTC\"}"
  }'

JavaScript/TypeScript Example¶

interface CreateOrganizationRequest {
  name: string;
  slug: string;
  settings?: string; // JSON string
}

async function createOrganization(
  name: string,
  slug: string,
  settings?: Record<string, any>
) {
  const response = await fetch('http://localhost:8080/api/v1/organizations', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name,
      slug,
      settings: settings ? JSON.stringify(settings) : undefined
    })
  });

  return await response.json();
}

// Usage
const org = await createOrganization(
  'ACME Corporation',
  'acme-corp',
  { theme: 'dark', timezone: 'UTC' }
);

console.log(`Organization created: ${org.id}`);

Python Example¶

import requests
import json

def create_organization(name, slug, access_token, settings=None):
    data = {
        'name': name,
        'slug': slug
    }

    if settings:
        data['settings'] = json.dumps(settings)

    response = requests.post(
        'http://localhost:8080/api/v1/organizations',
        headers={'Authorization': f'Bearer {access_token}'},
        json=data
    )

    return response.json()

# Usage
org = create_organization(
    'ACME Corporation',
    'acme-corp',
    access_token,
    settings={'theme': 'dark', 'timezone': 'UTC'}
)

print(f"Organization created: {org['id']}")

Go Example¶

type CreateOrganizationRequest struct {
    Name     string `json:"name"`
    Slug     string `json:"slug"`
    Settings string `json:"settings,omitempty"`
}

type Organization struct {
    ID        string `json:"id"`
    Name      string `json:"name"`
    Slug      string `json:"slug"`
    IsActive  bool   `json:"is_active"`
    Settings  string `json:"settings"`
    CreatedAt string `json:"created_at"`
    UpdatedAt string `json:"updated_at"`
}

func createOrganization(name, slug, accessToken string, settings map[string]interface{}) (*Organization, error) {
    reqData := CreateOrganizationRequest{
        Name: name,
        Slug: slug,
    }

    if len(settings) > 0 {
        settingsJSON, _ := json.Marshal(settings)
        reqData.Settings = string(settingsJSON)
    }

    jsonData, _ := json.Marshal(reqData)
    req, _ := http.NewRequest("POST",
        "http://localhost:8080/api/v1/organizations",
        bytes.NewBuffer(jsonData))

    req.Header.Set("Authorization", "Bearer "+accessToken)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var org Organization
    json.NewDecoder(resp.Body).Decode(&org)
    return &org, nil
}

Response¶

{
  "id": "org-789",
  "name": "ACME Corporation",
  "slug": "acme-corp",
  "is_active": true,
  "settings": "{\"theme\":\"dark\",\"timezone\":\"UTC\"}",
  "created_at": "2025-11-23T10:00:00Z",
  "updated_at": "2025-11-23T10:00:00Z"
}

List Organizations¶

List all organizations the authenticated user has access to.

REST API¶

Endpoint: GET /api/v1/organizations

curl Example¶

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  http://localhost:8080/api/v1/organizations

JavaScript/TypeScript Example¶

async function listOrganizations() {
  const response = await fetch('http://localhost:8080/api/v1/organizations', {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });

  return await response.json();
}

// Usage
const organizations = await listOrganizations();
console.log(`You have access to ${organizations.length} organizations`);

organizations.forEach(org => {
  console.log(`- ${org.name} (${org.slug})`);
});

Python Example¶

import requests

def list_organizations(access_token):
    response = requests.get(
        'http://localhost:8080/api/v1/organizations',
        headers={'Authorization': f'Bearer {access_token}'}
    )

    return response.json()

# Usage
organizations = list_organizations(access_token)
print(f"You have access to {len(organizations)} organizations")

for org in organizations:
    print(f"- {org['name']} ({org['slug']})")

Go Example¶

func listOrganizations(accessToken string) ([]Organization, error) {
    req, _ := http.NewRequest("GET",
        "http://localhost:8080/api/v1/organizations",
        nil)

    req.Header.Set("Authorization", "Bearer "+accessToken)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var orgs []Organization
    json.NewDecoder(resp.Body).Decode(&orgs)
    return orgs, nil
}

Response¶

[
  {
    "id": "org-789",
    "name": "ACME Corporation",
    "slug": "acme-corp",
    "is_active": true,
    "settings": "{\"theme\":\"dark\"}",
    "created_at": "2025-11-23T10:00:00Z",
    "updated_at": "2025-11-23T10:00:00Z"
  },
  {
    "id": "org-456",
    "name": "Tech Startup",
    "slug": "tech-startup",
    "is_active": true,
    "settings": "{}",
    "created_at": "2025-11-22T15:30:00Z",
    "updated_at": "2025-11-22T15:30:00Z"
  }
]

Get Organization Details¶

Get detailed information about a specific organization.

REST API¶

Endpoint: GET /api/v1/organizations/:id or GET /api/v1/organizations/slug/:slug

curl Example¶

# Get by ID
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  http://localhost:8080/api/v1/organizations/org-789

# Get by slug
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  http://localhost:8080/api/v1/organizations/slug/acme-corp

JavaScript/TypeScript Example¶

async function getOrganization(idOrSlug: string, bySlug = false) {
  const endpoint = bySlug
    ? `http://localhost:8080/api/v1/organizations/slug/${idOrSlug}`
    : `http://localhost:8080/api/v1/organizations/${idOrSlug}`;

  const response = await fetch(endpoint, {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });

  return await response.json();
}

// Usage
const org = await getOrganization('acme-corp', true);
console.log(`Organization: ${org.name}`);

Python Example¶

import requests

def get_organization(id_or_slug, access_token, by_slug=False):
    endpoint = (
        f'http://localhost:8080/api/v1/organizations/slug/{id_or_slug}'
        if by_slug
        else f'http://localhost:8080/api/v1/organizations/{id_or_slug}'
    )

    response = requests.get(
        endpoint,
        headers={'Authorization': f'Bearer {access_token}'}
    )

    return response.json()

# Usage
org = get_organization('acme-corp', access_token, by_slug=True)
print(f"Organization: {org['name']}")

Go Example¶

func getOrganization(idOrSlug, accessToken string, bySlug bool) (*Organization, error) {
    var endpoint string
    if bySlug {
        endpoint = fmt.Sprintf("http://localhost:8080/api/v1/organizations/slug/%s", idOrSlug)
    } else {
        endpoint = fmt.Sprintf("http://localhost:8080/api/v1/organizations/%s", idOrSlug)
    }

    req, _ := http.NewRequest("GET", endpoint, nil)
    req.Header.Set("Authorization", "Bearer "+accessToken)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var org Organization
    json.NewDecoder(resp.Body).Decode(&org)
    return &org, nil
}

Update Organization¶

Update organization name or settings.

REST API¶

Endpoint: PUT /api/v1/organizations/:id

curl Example¶

curl -X PUT http://localhost:8080/api/v1/organizations/org-789 \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME Corp Updated",
    "settings": "{\"theme\": \"light\", \"timezone\": \"America/New_York\"}"
  }'

JavaScript/TypeScript Example¶

async function updateOrganization(
  orgId: string,
  updates: {
    name?: string;
    settings?: Record<string, any>;
  }
) {
  const body: any = {};

  if (updates.name) {
    body.name = updates.name;
  }

  if (updates.settings) {
    body.settings = JSON.stringify(updates.settings);
  }

  const response = await fetch(
    `http://localhost:8080/api/v1/organizations/${orgId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(body)
    }
  );

  return await response.json();
}

// Usage
const updated = await updateOrganization('org-789', {
  name: 'ACME Corp Updated',
  settings: { theme: 'light', timezone: 'America/New_York' }
});

Python Example¶

import requests
import json

def update_organization(org_id, access_token, name=None, settings=None):
    data = {}

    if name:
        data['name'] = name

    if settings:
        data['settings'] = json.dumps(settings)

    response = requests.put(
        f'http://localhost:8080/api/v1/organizations/{org_id}',
        headers={'Authorization': f'Bearer {access_token}'},
        json=data
    )

    return response.json()

# Usage
updated = update_organization(
    'org-789',
    access_token,
    name='ACME Corp Updated',
    settings={'theme': 'light', 'timezone': 'America/New_York'}
)

Delete Organization¶

Permanently delete an organization and all its data.

REST API¶

Endpoint: DELETE /api/v1/organizations/:id

curl Example¶

curl -X DELETE \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  http://localhost:8080/api/v1/organizations/org-789

JavaScript/TypeScript Example¶

async function deleteOrganization(orgId: string) {
  const response = await fetch(
    `http://localhost:8080/api/v1/organizations/${orgId}`,
    {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );

  if (response.ok) {
    console.log('Organization deleted successfully');
  }
}

// Usage with confirmation
if (confirm('Are you sure you want to delete this organization?')) {
  await deleteOrganization('org-789');
}

Python Example¶

import requests

def delete_organization(org_id, access_token):
    response = requests.delete(
        f'http://localhost:8080/api/v1/organizations/{org_id}',
        headers={'Authorization': f'Bearer {access_token}'}
    )

    return response.ok

# Usage
if delete_organization('org-789', access_token):
    print('Organization deleted successfully')

Warning: This action is irreversible and will delete all organization data including files, directories, and members.

Add Members¶

Add a user to an organization with a specific role.

REST API¶

Endpoint: POST /api/v1/organizations/:id/members

curl Example¶

curl -X POST http://localhost:8080/api/v1/organizations/org-789/members \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-456",
    "role_id": "role-123"
  }'

JavaScript/TypeScript Example¶

async function addOrganizationMember(
  orgId: string,
  userId: string,
  roleId: string
) {
  const response = await fetch(
    `http://localhost:8080/api/v1/organizations/${orgId}/members`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        user_id: userId,
        role_id: roleId
      })
    }
  );

  return await response.json();
}

// Usage
const member = await addOrganizationMember('org-789', 'user-456', 'role-123');
console.log(`User added with role: ${member.role_id}`);

Python Example¶

import requests

def add_organization_member(org_id, user_id, role_id, access_token):
    response = requests.post(
        f'http://localhost:8080/api/v1/organizations/{org_id}/members',
        headers={'Authorization': f'Bearer {access_token}'},
        json={
            'user_id': user_id,
            'role_id': role_id
        }
    )

    return response.json()

# Usage
member = add_organization_member('org-789', 'user-456', 'role-123', access_token)
print(f"User added with role: {member['role_id']}")

List Organization Members¶

Get all members of an organization.

REST API¶

Endpoint: GET /api/v1/organizations/:id/members

curl Example¶

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  http://localhost:8080/api/v1/organizations/org-789/members

JavaScript/TypeScript Example¶

async function listOrganizationMembers(orgId: string) {
  const response = await fetch(
    `http://localhost:8080/api/v1/organizations/${orgId}/members`,
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );

  return await response.json();
}

// Usage
const members = await listOrganizationMembers('org-789');
console.log(`Organization has ${members.length} members`);

members.forEach(member => {
  console.log(`- User ${member.user_id} (Role: ${member.role_id})`);
});

Python Example¶

import requests

def list_organization_members(org_id, access_token):
    response = requests.get(
        f'http://localhost:8080/api/v1/organizations/{org_id}/members',
        headers={'Authorization': f'Bearer {access_token}'}
    )

    return response.json()

# Usage
members = list_organization_members('org-789', access_token)
print(f"Organization has {len(members)} members")

for member in members:
    print(f"- User {member['user_id']} (Role: {member['role_id']})")

Update Member Role¶

Change a member's role within the organization.

REST API¶

Endpoint: PUT /api/v1/organizations/:id/members/:userId/role

curl Example¶

curl -X PUT http://localhost:8080/api/v1/organizations/org-789/members/user-456/role \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": "role-456"
  }'

JavaScript/TypeScript Example¶

async function updateMemberRole(
  orgId: string,
  userId: string,
  roleId: string
) {
  const response = await fetch(
    `http://localhost:8080/api/v1/organizations/${orgId}/members/${userId}/role`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        role_id: roleId
      })
    }
  );

  return await response.json();
}

// Usage
const updated = await updateMemberRole('org-789', 'user-456', 'role-admin');
console.log('Member role updated successfully');

Python Example¶

import requests

def update_member_role(org_id, user_id, role_id, access_token):
    response = requests.put(
        f'http://localhost:8080/api/v1/organizations/{org_id}/members/{user_id}/role',
        headers={'Authorization': f'Bearer {access_token}'},
        json={'role_id': role_id}
    )

    return response.json()

# Usage
updated = update_member_role('org-789', 'user-456', 'role-admin', access_token)
print('Member role updated successfully')

Remove Member¶

Remove a user from organization membership.

REST API¶

Endpoint: DELETE /api/v1/organizations/:id/members/:userId

curl Example¶

curl -X DELETE \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  http://localhost:8080/api/v1/organizations/org-789/members/user-456

JavaScript/TypeScript Example¶

async function removeOrganizationMember(orgId: string, userId: string) {
  const response = await fetch(
    `http://localhost:8080/api/v1/organizations/${orgId}/members/${userId}`,
    {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );

  if (response.ok) {
    console.log('Member removed successfully');
  }
}

// Usage
await removeOrganizationMember('org-789', 'user-456');

Python Example¶

import requests

def remove_organization_member(org_id, user_id, access_token):
    response = requests.delete(
        f'http://localhost:8080/api/v1/organizations/{org_id}/members/{user_id}',
        headers={'Authorization': f'Bearer {access_token}'}
    )

    return response.ok

# Usage
if remove_organization_member('org-789', 'user-456', access_token):
    print('Member removed successfully')

Note: Cannot remove the last admin from an organization.

Set Primary Organization¶

Set which organization is the user's primary organization.

REST API¶

Endpoint: PUT /api/v1/user/organizations/:id/primary

curl Example¶

curl -X PUT \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  http://localhost:8080/api/v1/user/organizations/org-789/primary

JavaScript/TypeScript Example¶

async function setPrimaryOrganization(orgId: string) {
  const response = await fetch(
    `http://localhost:8080/api/v1/user/organizations/${orgId}/primary`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );

  if (response.ok) {
    console.log('Primary organization updated');
  }
}

// Usage
await setPrimaryOrganization('org-789');

Python Example¶

import requests

def set_primary_organization(org_id, access_token):
    response = requests.put(
        f'http://localhost:8080/api/v1/user/organizations/{org_id}/primary',
        headers={'Authorization': f'Bearer {access_token}'}
    )

    return response.ok

# Usage
if set_primary_organization('org-789', access_token):
    print('Primary organization updated')

Organization Management Examples¶

Table of Contents¶

Create Organization¶

REST API¶

curl Example¶

JavaScript/TypeScript Example¶

Python Example¶

Go Example¶

Response¶

List Organizations¶

REST API¶

curl Example¶

JavaScript/TypeScript Example¶

Python Example¶

Go Example¶

Response¶

Get Organization Details¶

REST API¶

curl Example¶

JavaScript/TypeScript Example¶

Python Example¶

Go Example¶

Update Organization¶

REST API¶

curl Example¶

JavaScript/TypeScript Example¶

Python Example¶

Delete Organization¶

REST API¶

curl Example¶

JavaScript/TypeScript Example¶

Python Example¶

Add Members¶

REST API¶

curl Example¶

JavaScript/TypeScript Example¶

Python Example¶

List Organization Members¶

REST API¶

curl Example¶

JavaScript/TypeScript Example¶

Python Example¶

Update Member Role¶

REST API¶

curl Example¶

JavaScript/TypeScript Example¶

Python Example¶

Remove Member¶

REST API¶

curl Example¶

JavaScript/TypeScript Example¶

Python Example¶

Set Primary Organization¶

REST API¶

curl Example¶

JavaScript/TypeScript Example¶

Python Example¶

See Also¶