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)

Tenant Provisioning
Tenant Management
Data Models
Error Handling
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

Tenant API Routes Documentation

Tenant API Routes Documentation

Overview

Table of Contents

Tenant Provisioning

Create Tenant

Get Tenant Details

Delete Tenant

Tenant Management

Update Tenant

Add Member

List Members

Remove Member

Data Models

Tenant Status

Isolation Mode

Quota Configuration

Member Roles

Error Handling

HTTP Status Codes

Common Error Scenarios

Examples

Complete Tenant Lifecycle

Hierarchical Multi-Tenancy

Filtering and Pagination

Rate Limiting

Best Practices

Tenant Naming

Quota Management

Member Management

Error Handling

Integration Examples

Python

JavaScript/Node.js

Changelog

Version 1.0.0 (Current)

Support