---
title: "Tenant API Routes Documentation"
---

# Tenant API Routes Documentation

:::caution[Not served by the HTTP gateway]
The `heliosdb-full` server's HTTP gateway (port 8443) does not serve these routes in
the current release; a request to them returns 404. The routes the gateway serves are
listed in the [REST API overview](/docs/full/api/rest/readme/). Use SQL from a
PostgreSQL client for administration, and contact
[support@heliosdb.com](mailto:support@heliosdb.com) if you need this API.
:::

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](#tenant-provisioning)
   - [Create Tenant](#create-tenant)
   - [Get Tenant Details](#get-tenant-details)
   - [Delete Tenant](#delete-tenant)
2. [Tenant Management](#tenant-management)
   - [Update Tenant](#update-tenant)
   - [Add Member](#add-member)
   - [List Members](#list-members)
   - [Remove Member](#remove-member)
3. [Data Models](#data-models)
4. [Error Handling](#error-handling)
5. [Examples](#examples)

---

## Tenant Provisioning

### Create Tenant

Create a new tenant with specified configuration.

**Endpoint:** `POST /api/v1/tenants`

**Request Body:**

```json
{
  "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`

```json
{
  "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:**

```bash
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`

```json
{
  "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:**

```bash
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`

```json
{
  "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:**

```bash
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:**

```json
{
  "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`

```json
{
  "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:**

```bash
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:**

```json
{
  "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`

```json
{
  "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:**

```bash
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`

```json
{
  "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:**

```bash
# 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`

```json
{
  "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:**

```bash
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 state

Represents the current state of a tenant:

- `active` - Tenant is 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:

```json
{
  "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:**

```json
{
  "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:

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

### HTTP Response 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:**

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

**Resource Not Found:**

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

**Conflict:**

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

---

## Examples

### Complete Tenant Lifecycle

```bash
# 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

```bash
# 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

```bash
# 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 Response Codes
- Parse error messages for actionable information
- Implement retry logic with exponential backoff
- Log errors for debugging and monitoring

---

## Integration Examples

### Python

```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

```javascript
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`);
})();
```

---

## Support

For questions, issues, or feature requests:

- **Documentation:** https://www.heliosdb.com/docs/full/
- **Support Email:** support@heliosdb.com

---


**API Version:** 1.0.0