Skip to content

Tenant API Routes Documentation

Complete API reference for HeliosDB multi-tenancy management endpoints.

Overview

The Tenant API provides comprehensive HTTP endpoints for managing tenant lifecycle, configuration, and member access control. All endpoints follow RESTful conventions and return JSON responses.

Base Path: /api/v1/tenants

Version: 1.0.0

Authentication: All endpoints require valid authentication (implementation-specific)

Table of Contents

  1. Tenant Provisioning
  2. Create Tenant
  3. Get Tenant Details
  4. Delete Tenant
  5. Tenant Management
  6. Update Tenant
  7. Add Member
  8. List Members
  9. Remove Member
  10. Data Models
  11. Error Handling
  12. Examples

Tenant Provisioning

Create Tenant

Create a new tenant with specified configuration.

Endpoint: POST /api/v1/tenants

Request Body:

{
  "name": "string",                    // Required: 3-64 alphanumeric chars + underscores
  "quotas": {                          // Optional: Resource quotas
    "storage_quota_bytes": "number",
    "qps_limit": "number",
    "max_connections": "number",
    "compute_quota_cores": "number"
  },
  "isolation_mode": "string",          // Optional: "logical" | "physical" | "hybrid"
  "parent_id": "uuid",                 // Optional: Parent tenant UUID
  "settings": {},                      // Optional: Custom JSON settings
  "features": ["string"],              // Optional: Enabled feature flags
  "tags": {                            // Optional: Metadata key-value pairs
    "key": "value"
  }
}

Response: 201 Created

{
  "id": "uuid",
  "name": "string",
  "status": "active" | "provisioning" | "suspended" | "deleting" | "deleted",
  "isolation_mode": "logical" | "physical" | "hybrid",
  "created_at": "ISO8601 timestamp",
  "quotas": {
    "storage_quota_bytes": "number",
    "qps_limit": "number",
    "max_connections": "number",
    "compute_quota_cores": "number"
  },
  "message": "Tenant 'name' created successfully"
}

Error Responses:

  • 400 Bad Request - Invalid input or validation error
  • 409 Conflict - Tenant with same name already exists
  • 500 Internal Server Error - Server-side error

Example:

curl -X POST https://api.heliosdb.com/api/v1/tenants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "acme_corp",
    "quotas": {
      "storage_quota_bytes": 107374182400,
      "qps_limit": 1000,
      "max_connections": 100
    },
    "isolation_mode": "logical",
    "features": ["ml_features", "advanced_analytics"],
    "tags": {
      "tier": "premium",
      "region": "us-east-1"
    }
  }'

Get Tenant Details

Retrieve comprehensive details for a specific tenant.

Endpoint: GET /api/v1/tenants/{id}

Path Parameters:

  • id (UUID) - Tenant identifier

Response: 200 OK

{
  "id": "uuid",
  "name": "string",
  "status": "active" | "provisioning" | "suspended" | "deleting" | "deleted",
  "isolation_mode": "logical" | "physical" | "hybrid",
  "parent_id": "uuid | null",
  "created_at": "ISO8601 timestamp",
  "updated_at": "ISO8601 timestamp",
  "quotas": {
    "storage_quota_bytes": "number",
    "qps_limit": "number",
    "max_connections": "number",
    "compute_quota_cores": "number"
  },
  "settings": {},
  "features": ["string"],
  "encryption_key_id": "string | null",
  "tags": {
    "key": "value"
  }
}

Error Responses:

  • 404 Not Found - Tenant does not exist
  • 500 Internal Server Error - Server-side error

Example:

curl -X GET https://api.heliosdb.com/api/v1/tenants/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <token>"

Delete Tenant

Deactivate and remove a tenant. Initiates cleanup procedures for all tenant resources.

Endpoint: DELETE /api/v1/tenants/{id}

Path Parameters:

  • id (UUID) - Tenant identifier

Response: 200 OK

{
  "id": "uuid",
  "name": "string",
  "message": "Tenant 'name' has been deleted",
  "deleted_at": "ISO8601 timestamp"
}

Error Responses:

  • 404 Not Found - Tenant does not exist
  • 409 Conflict - Tenant has child tenants or active resources
  • 500 Internal Server Error - Server-side error

Notes:

  • Tenants with child tenants cannot be deleted
  • Deletion is permanent and cannot be undone
  • All tenant data will be purged according to retention policies

Example:

curl -X DELETE https://api.heliosdb.com/api/v1/tenants/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <token>"

Tenant Management

Update Tenant

Update tenant configuration. Only provided fields will be updated.

Endpoint: PUT /api/v1/tenants/{id}

Path Parameters:

  • id (UUID) - Tenant identifier

Request Body:

{
  "name": "string",                    // Optional: New tenant name
  "quotas": {                          // Optional: Updated quotas
    "storage_quota_bytes": "number",
    "qps_limit": "number",
    "max_connections": "number",
    "compute_quota_cores": "number"
  },
  "settings": {},                      // Optional: Updated settings
  "features": ["string"],              // Optional: Updated features
  "tags": {                            // Optional: Updated tags
    "key": "value"
  }
}

Response: 200 OK

{
  "id": "uuid",
  "name": "string",
  "status": "active" | "provisioning" | "suspended" | "deleting" | "deleted",
  "updated_at": "ISO8601 timestamp",
  "message": "Tenant 'name' updated successfully"
}

Error Responses:

  • 400 Bad Request - Invalid input or validation error
  • 404 Not Found - Tenant does not exist
  • 500 Internal Server Error - Server-side error

Example:

curl -X PUT https://api.heliosdb.com/api/v1/tenants/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "quotas": {
      "storage_quota_bytes": 214748364800,
      "qps_limit": 2000
    },
    "features": ["ml_features", "real_time_analytics"],
    "tags": {
      "tier": "enterprise"
    }
  }'

Add Member

Add a new member to a tenant with specified role and permissions.

Endpoint: POST /api/v1/tenants/{id}/members

Path Parameters:

  • id (UUID) - Tenant identifier

Request Body:

{
  "user_identifier": "string",         // Required: User ID or email
  "role": "admin" | "editor" | "viewer", // Required: Member role
  "metadata": {                        // Optional: Member metadata
    "key": "value"
  }
}

Roles:

  • admin - Full administrative access to tenant
  • editor - Read and write access to tenant resources
  • viewer - Read-only access to tenant resources

Response: 201 Created

{
  "tenant_id": "uuid",
  "member_id": "uuid",
  "user_identifier": "string",
  "role": "admin" | "editor" | "viewer",
  "added_at": "ISO8601 timestamp",
  "message": "Member added successfully to tenant {id}"
}

Error Responses:

  • 400 Bad Request - Invalid input or tenant is inactive
  • 403 Forbidden - Member limit exceeded
  • 404 Not Found - Tenant does not exist
  • 409 Conflict - Member already exists
  • 500 Internal Server Error - Server-side error

Limits:

  • Maximum 100 members per tenant (default)

Example:

curl -X POST https://api.heliosdb.com/api/v1/tenants/550e8400-e29b-41d4-a716-446655440000/members \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "user_identifier": "user@example.com",
    "role": "editor",
    "metadata": {
      "department": "Engineering",
      "team": "Backend"
    }
  }'

List Members

Retrieve a list of all members for a tenant with optional filtering and pagination.

Endpoint: GET /api/v1/tenants/{id}/members

Path Parameters:

  • id (UUID) - Tenant identifier

Query Parameters:

  • role (string, optional) - Filter by role: admin, editor, or viewer
  • offset (integer, optional) - Pagination offset (default: 0)
  • limit (integer, optional) - Pagination limit (default: 50, max: 100)

Response: 200 OK

{
  "tenant_id": "uuid",
  "members": [
    {
      "id": "uuid",
      "user_identifier": "string",
      "role": "admin" | "editor" | "viewer",
      "added_at": "ISO8601 timestamp",
      "metadata": {
        "key": "value"
      }
    }
  ],
  "total_count": "number"
}

Error Responses:

  • 404 Not Found - Tenant does not exist
  • 500 Internal Server Error - Server-side error

Example:

# List all members
curl -X GET https://api.heliosdb.com/api/v1/tenants/550e8400-e29b-41d4-a716-446655440000/members \
  -H "Authorization: Bearer <token>"

# List only admin members with pagination
curl -X GET "https://api.heliosdb.com/api/v1/tenants/550e8400-e29b-41d4-a716-446655440000/members?role=admin&offset=0&limit=20" \
  -H "Authorization: Bearer <token>"

Remove Member

Remove a member from a tenant. The member will lose all access to the tenant.

Endpoint: DELETE /api/v1/tenants/{id}/members/{member_id}

Path Parameters:

  • id (UUID) - Tenant identifier
  • member_id (UUID) - Member identifier

Response: 200 OK

{
  "tenant_id": "uuid",
  "member_id": "uuid",
  "message": "Member {member_id} removed from tenant {tenant_id}",
  "removed_at": "ISO8601 timestamp"
}

Error Responses:

  • 404 Not Found - Tenant or member does not exist
  • 500 Internal Server Error - Server-side error

Example:

curl -X DELETE https://api.heliosdb.com/api/v1/tenants/550e8400-e29b-41d4-a716-446655440000/members/660e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer <token>"

Data Models

Tenant Status

Represents the current state of a tenant:

  • active - Tenant is fully operational
  • provisioning - Tenant is being set up
  • suspended - Tenant is temporarily disabled
  • deleting - Tenant is being removed
  • deleted - Tenant has been removed (tombstone)

Isolation Mode

Determines how tenant data is isolated:

  • logical - Row-level security using tenant_id column (default)
  • physical - Separate database or schema per tenant
  • hybrid - Combination of logical and physical isolation

Quota Configuration

Resource limits for tenant:

{
  "storage_quota_bytes": "number",     // Storage limit in bytes
  "qps_limit": "number",               // Queries per second limit
  "max_connections": "number",         // Maximum concurrent connections
  "compute_quota_cores": "number"      // CPU cores allocated
}

Default Quotas:

{
  "storage_quota_bytes": 10737418240,  // 10 GB
  "qps_limit": 100,
  "max_connections": 10,
  "compute_quota_cores": 1.0
}

Member Roles

Access control roles for tenant members:

Role Permissions
admin Full access: manage tenant, members, and all resources
editor Read/write access to tenant resources
viewer Read-only access to tenant resources

Error Handling

All error responses follow a consistent format:

{
  "error": "Error Type",
  "message": "Human-readable error description",
  "code": "number",                    // HTTP status code
  "tenant_id": "uuid | null"           // Relevant tenant ID if applicable
}

HTTP Status Codes

  • 200 OK - Request successful
  • 201 Created - Resource created successfully
  • 400 Bad Request - Invalid request or validation error
  • 403 Forbidden - Operation not allowed (quota exceeded, etc.)
  • 404 Not Found - Resource does not exist
  • 409 Conflict - Resource conflict (duplicate name, has children, etc.)
  • 500 Internal Server Error - Server-side error

Common Error Scenarios

Validation Errors:

{
  "error": "Bad Request",
  "message": "Validation error: name must be at least 3 characters",
  "code": 400
}

Resource Not Found:

{
  "error": "Not Found",
  "message": "Tenant not found: 550e8400-e29b-41d4-a716-446655440000",
  "code": 404,
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000"
}

Conflict:

{
  "error": "Conflict",
  "message": "Tenant already exists: acme_corp",
  "code": 409
}

Examples

Complete Tenant Lifecycle

# 1. Create tenant
TENANT_ID=$(curl -X POST https://api.heliosdb.com/api/v1/tenants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "example_tenant",
    "quotas": {
      "storage_quota_bytes": 50000000000,
      "qps_limit": 500
    },
    "features": ["analytics"]
  }' | jq -r '.id')

# 2. Update tenant settings
curl -X PUT https://api.heliosdb.com/api/v1/tenants/$TENANT_ID \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "quotas": {
      "qps_limit": 1000
    },
    "tags": {
      "environment": "production"
    }
  }'

# 3. Add members
curl -X POST https://api.heliosdb.com/api/v1/tenants/$TENANT_ID/members \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "user_identifier": "admin@example.com",
    "role": "admin"
  }'

curl -X POST https://api.heliosdb.com/api/v1/tenants/$TENANT_ID/members \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "user_identifier": "user@example.com",
    "role": "editor"
  }'

# 4. List members
curl -X GET https://api.heliosdb.com/api/v1/tenants/$TENANT_ID/members \
  -H "Authorization: Bearer <token>"

# 5. Get tenant details
curl -X GET https://api.heliosdb.com/api/v1/tenants/$TENANT_ID \
  -H "Authorization: Bearer <token>"

Hierarchical Multi-Tenancy

# Create parent tenant
PARENT_ID=$(curl -X POST https://api.heliosdb.com/api/v1/tenants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "parent_org",
    "quotas": {
      "storage_quota_bytes": 1000000000000
    }
  }' | jq -r '.id')

# Create child tenant
CHILD_ID=$(curl -X POST https://api.heliosdb.com/api/v1/tenants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d "{
    \"name\": \"child_dept\",
    \"parent_id\": \"$PARENT_ID\",
    \"quotas\": {
      \"storage_quota_bytes\": 100000000000
    }
  }" | jq -r '.id')

Filtering and Pagination

# Get all admin members with pagination
curl -X GET "https://api.heliosdb.com/api/v1/tenants/$TENANT_ID/members?role=admin&offset=0&limit=10" \
  -H "Authorization: Bearer <token>"

# Get second page of members
curl -X GET "https://api.heliosdb.com/api/v1/tenants/$TENANT_ID/members?offset=10&limit=10" \
  -H "Authorization: Bearer <token>"

Rate Limiting

API requests are subject to rate limiting based on tenant quotas:

  • Default: 100 requests/second per tenant
  • Configurable via qps_limit quota
  • Rate limit headers included in responses:
  • X-RateLimit-Limit - Request limit
  • X-RateLimit-Remaining - Remaining requests
  • X-RateLimit-Reset - Time until reset (Unix timestamp)

When rate limit is exceeded, API returns 429 Too Many Requests.

Best Practices

Tenant Naming

  • Use descriptive, consistent naming conventions
  • Avoid special characters (alphanumeric + underscores only)
  • Keep names between 3-64 characters
  • Consider using prefixes for organization: org_acme, dept_engineering

Quota Management

  • Start with conservative quotas and increase as needed
  • Monitor usage via analytics endpoints
  • Set quotas based on workload characteristics
  • Consider burst capacity for spiky workloads

Member Management

  • Follow principle of least privilege (use viewer role by default)
  • Regular audit of member access
  • Remove members promptly when access is no longer needed
  • Use metadata for organizational tracking

Error Handling

  • Always check HTTP status codes
  • Parse error messages for actionable information
  • Implement retry logic with exponential backoff
  • Log errors for debugging and monitoring

Integration Examples

Python

import requests

BASE_URL = "https://api.heliosdb.com/api/v1"
TOKEN = "your-auth-token"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

# Create tenant
response = requests.post(
    f"{BASE_URL}/tenants",
    headers=headers,
    json={
        "name": "python_tenant",
        "quotas": {
            "storage_quota_bytes": 100000000000,
            "qps_limit": 1000
        }
    }
)

tenant = response.json()
tenant_id = tenant["id"]

# Add member
requests.post(
    f"{BASE_URL}/tenants/{tenant_id}/members",
    headers=headers,
    json={
        "user_identifier": "user@example.com",
        "role": "editor"
    }
)

# Get tenant details
tenant_details = requests.get(
    f"{BASE_URL}/tenants/{tenant_id}",
    headers=headers
).json()

print(f"Tenant: {tenant_details['name']}")
print(f"Status: {tenant_details['status']}")

JavaScript/Node.js

const axios = require('axios');

const BASE_URL = 'https://api.heliosdb.com/api/v1';
const TOKEN = 'your-auth-token';

const headers = {
  'Authorization': `Bearer ${TOKEN}`,
  'Content-Type': 'application/json'
};

// Create tenant
const createTenant = async () => {
  const response = await axios.post(`${BASE_URL}/tenants`, {
    name: 'js_tenant',
    quotas: {
      storage_quota_bytes: 100000000000,
      qps_limit: 1000
    }
  }, { headers });

  return response.data.id;
};

// Add member
const addMember = async (tenantId) => {
  await axios.post(`${BASE_URL}/tenants/${tenantId}/members`, {
    user_identifier: 'user@example.com',
    role: 'editor'
  }, { headers });
};

// List members
const listMembers = async (tenantId) => {
  const response = await axios.get(
    `${BASE_URL}/tenants/${tenantId}/members`,
    { headers }
  );

  return response.data.members;
};

// Usage
(async () => {
  const tenantId = await createTenant();
  await addMember(tenantId);
  const members = await listMembers(tenantId);
  console.log(`Tenant has ${members.length} members`);
})();

Changelog

Version 1.0.0 (Current)

  • Initial release of Tenant API
  • Tenant provisioning endpoints (create, get, delete)
  • Tenant management endpoints (update)
  • Member management endpoints (add, list, remove)
  • Comprehensive error handling
  • Support for hierarchical multi-tenancy
  • Quota management
  • Role-based access control

Support

For questions, issues, or feature requests:

  • Documentation: https://docs.heliosdb.com
  • API Status: https://status.heliosdb.com
  • Support Email: support@heliosdb.com
  • GitHub Issues: https://github.com/heliosdb/heliosdb/issues

Last Updated: 2025-12-09

API Version: 1.0.0