---
title: "Tenant Configuration API Documentation"
---

# Tenant Configuration API 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.
:::

**Version:** v1
**Base Path:** `/api/v1/tenants/{id}/config`
**Authentication:** Required
**Rate Limit:** 100 requests/minute per tenant

## Overview

The Tenant Configuration API provides comprehensive management of tenant-specific configurations including performance settings, security policies, backup configurations, replication settings, compliance requirements, and custom settings.

## Table of Contents

- [Endpoints](#endpoints)
  - [GET /tenants/{id}/config](#get-tenantsidconfig)
  - [PUT /tenants/{id}/config](#put-tenantsidconfig)
  - [GET /tenants/{id}/features](#get-tenantsidfeatures)
- [Data Models](#data-models)
- [Configuration Categories](#configuration-categories)
- [Validation Rules](#validation-rules)
- [Examples](#examples)
- [Error Handling](#error-handling)

---

## Endpoints

### GET /tenants/{id}/config

Retrieves the complete configuration for a tenant.

#### Request

```http
GET /api/v1/tenants/{id}/config HTTP/1.1
Host: api.heliosdb.com
Authorization: Bearer {token}
```

**Path Parameters:**
- `id` (UUID, required): Tenant identifier

#### Response

**Success (200 OK):**

```json
{
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "performance": {
    "cache_size_mb": 1024,
    "max_parallel_workers": 8,
    "enable_query_optimization": true,
    "enable_result_caching": true,
    "enable_adaptive_indexing": true,
    "query_timeout_secs": 300,
    "query_memory_limit_mb": 4096,
    "collect_query_stats": true
  },
  "security": {
    "encryption_at_rest": true,
    "encryption_in_transit": true,
    "encryption_algorithm": "AES-256-GCM",
    "kms_key_id": "arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012",
    "enable_rls": true,
    "enable_column_encryption": false,
    "password_complexity": 3,
    "session_timeout_mins": 30,
    "require_mfa": false,
    "allowed_ips": ["10.0.0.0/8", "172.16.0.0/12"],
    "enable_audit_log": true,
    "audit_retention_days": 90
  },
  "backup": {
    "enabled": true,
    "frequency_hours": 24,
    "retention_days": 30,
    "full_backup_interval": 7,
    "destinations": [
      {
        "destination_type": "s3",
        "bucket": "heliosdb-backups",
        "region": "us-east-1",
        "path": "/tenant-550e8400",
        "credentials_id": "aws-creds-123"
      }
    ],
    "enable_pitr": true,
    "pitr_retention_days": 7,
    "encrypt_backups": true,
    "compress_backups": true
  },
  "replication": {
    "enabled": false,
    "mode": "async",
    "regions": [],
    "consistency_level": "eventual",
    "max_lag_seconds": 60,
    "enable_auto_failover": true,
    "failover_priority": []
  },
  "compliance": {
    "gdpr": false,
    "hipaa": false,
    "soc2": false,
    "pci_dss": false,
    "data_residency": [],
    "enable_retention_policies": false,
    "default_retention_days": 365,
    "enable_anonymization": false,
    "enable_rtbf": false
  },
  "custom_settings": {
    "custom_key": "custom_value"
  },
  "updated_at": "2025-12-09T10:30:00Z"
}
```

**Error Responses:**
- `404 Not Found`: Tenant does not exist
- `500 Internal Server Error`: Server-side error

---

### PUT /tenants/{id}/config

Updates tenant configuration with partial updates. Only provided fields will be modified.

#### Request

```http
PUT /api/v1/tenants/{id}/config HTTP/1.1
Host: api.heliosdb.com
Authorization: Bearer {token}
Content-Type: application/json

{
  "performance": {
    "cache_size_mb": 2048,
    "max_parallel_workers": 16
  },
  "security": {
    "require_mfa": true,
    "session_timeout_mins": 60
  },
  "compliance": {
    "gdpr": true,
    "data_residency": ["EU"]
  }
}
```

**Path Parameters:**
- `id` (UUID, required): Tenant identifier

**Request Body Fields (all optional):**
- `performance` (object): Performance configuration
- `security` (object): Security configuration
- `backup` (object): Backup configuration
- `replication` (object): Replication configuration
- `compliance` (object): Compliance configuration
- `custom_settings` (object): Custom key-value settings

#### Response

**Success (200 OK):**

```json
{
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Successfully updated 4 configuration field(s)",
  "updated_fields": [
    "performance.cache_size_mb",
    "performance.max_parallel_workers",
    "security.require_mfa",
    "security.session_timeout_mins"
  ],
  "updated_at": "2025-12-09T10:35:00Z"
}
```

**Error Responses:**
- `400 Bad Request`: Invalid configuration or validation error
- `404 Not Found`: Tenant does not exist
- `500 Internal Server Error`: Server-side error

---

### GET /tenants/{id}/features

Lists all available features for the tenant with enabled status.

#### Request

```http
GET /api/v1/tenants/{id}/features HTTP/1.1
Host: api.heliosdb.com
Authorization: Bearer {token}
```

**Path Parameters:**
- `id` (UUID, required): Tenant identifier

#### Response

**Success (200 OK):**

```json
{
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "features": [
    {
      "name": "advanced_analytics",
      "enabled": true,
      "available": true,
      "description": "Advanced analytics and reporting capabilities",
      "tier_required": "Pro"
    },
    {
      "name": "ml_features",
      "enabled": false,
      "available": true,
      "description": "Machine learning and AI features",
      "tier_required": "Enterprise"
    },
    {
      "name": "row_level_security",
      "enabled": true,
      "available": true,
      "description": "Row-level security for data isolation",
      "tier_required": "Basic"
    },
    {
      "name": "encryption_at_rest",
      "enabled": true,
      "available": true,
      "description": "Data encryption at rest",
      "tier_required": "Basic"
    },
    {
      "name": "multi_factor_auth",
      "enabled": false,
      "available": true,
      "description": "Multi-factor authentication requirement",
      "tier_required": "Pro"
    }
  ],
  "total_enabled": 12,
  "total_available": 18
}
```

**Error Responses:**
- `404 Not Found`: Tenant does not exist
- `500 Internal Server Error`: Server-side error

---

## Data Models

### PerformanceConfig

Controls query execution and caching behavior.

| Field | Type | Description | Range/Values | Default |
|-------|------|-------------|--------------|---------|
| `cache_size_mb` | integer | Result cache size in MB | 0-100000 | 1024 |
| `max_parallel_workers` | integer | Maximum parallel query workers | 1-128 | 8 |
| `enable_query_optimization` | boolean | Enable query optimizer | true/false | true |
| `enable_result_caching` | boolean | Enable result caching | true/false | true |
| `enable_adaptive_indexing` | boolean | Enable adaptive indexing | true/false | true |
| `query_timeout_secs` | integer | Query timeout in seconds | 1-3600 | 300 |
| `query_memory_limit_mb` | integer | Per-query memory limit in MB | 256-65536 | 4096 |
| `collect_query_stats` | boolean | Collect query statistics | true/false | true |

### SecurityConfig

Defines security and access control policies.

| Field | Type | Description | Range/Values | Default |
|-------|------|-------------|--------------|---------|
| `encryption_at_rest` | boolean | Enable encryption at rest | true/false | true |
| `encryption_in_transit` | boolean | Enable encryption in transit | true/false | true |
| `encryption_algorithm` | string | Encryption algorithm | "AES-256-GCM", "AES-128-GCM" | "AES-256-GCM" |
| `kms_key_id` | string | KMS key identifier | Valid KMS ARN | null |
| `enable_rls` | boolean | Enable row-level security | true/false | true |
| `enable_column_encryption` | boolean | Enable column encryption | true/false | false |
| `password_complexity` | integer | Password complexity level | 1-5 | 3 |
| `session_timeout_mins` | integer | Session timeout in minutes | 5-1440 | 30 |
| `require_mfa` | boolean | Require multi-factor auth | true/false | false |
| `allowed_ips` | array[string] | Allowed IP addresses (CIDR) | Valid CIDR notation | [] |
| `enable_audit_log` | boolean | Enable audit logging | true/false | true |
| `audit_retention_days` | integer | Audit log retention days | 1-3650 | 90 |

### BackupConfig

Configures backup policies and schedules.

| Field | Type | Description | Range/Values | Default |
|-------|------|-------------|--------------|---------|
| `enabled` | boolean | Enable automatic backups | true/false | true |
| `frequency_hours` | integer | Backup frequency in hours | 1-168 | 24 |
| `retention_days` | integer | Backup retention days | 1-365 | 30 |
| `full_backup_interval` | integer | Full backup interval (incrementals) | 1-30 | 7 |
| `destinations` | array | Backup destinations | BackupDestination[] | [] |
| `enable_pitr` | boolean | Enable point-in-time recovery | true/false | true |
| `pitr_retention_days` | integer | PITR retention days | 1-30 | 7 |
| `encrypt_backups` | boolean | Encrypt backup data | true/false | true |
| `compress_backups` | boolean | Compress backup data | true/false | true |

### ReplicationConfig

Manages multi-region replication settings.

| Field | Type | Description | Range/Values | Default |
|-------|------|-------------|--------------|---------|
| `enabled` | boolean | Enable replication | true/false | false |
| `mode` | string | Replication mode | "async", "sync", "semi-sync" | "async" |
| `regions` | array[string] | Target regions | AWS regions | [] |
| `consistency_level` | string | Consistency level | "eventual", "read_after_write", "strong" | "eventual" |
| `max_lag_seconds` | integer | Max replication lag (seconds) | 1-300 | 60 |
| `enable_auto_failover` | boolean | Enable automatic failover | true/false | true |
| `failover_priority` | array[string] | Failover priority order | Region names | [] |

### ComplianceConfig

Configures compliance and regulatory requirements.

| Field | Type | Description | Range/Values | Default |
|-------|------|-------------|--------------|---------|
| `gdpr` | boolean | Enable GDPR compliance | true/false | false |
| `hipaa` | boolean | Enable HIPAA compliance | true/false | false |
| `soc2` | boolean | Enable SOC2 compliance | true/false | false |
| `pci_dss` | boolean | Enable PCI-DSS compliance | true/false | false |
| `data_residency` | array[string] | Data residency requirements | Country codes | [] |
| `enable_retention_policies` | boolean | Enable retention policies | true/false | false |
| `default_retention_days` | integer | Default retention period | 1-3650 | 365 |
| `enable_anonymization` | boolean | Enable data anonymization | true/false | false |
| `enable_rtbf` | boolean | Enable right-to-be-forgotten | true/false | false |

---

## Configuration Categories

### 1. Performance Configuration

**Purpose:** Optimize query execution and resource utilization.

**Key Settings:**
- **Cache Size**: Controls memory allocation for query result caching
- **Parallel Workers**: Number of concurrent workers for query execution
- **Query Optimization**: Enable/disable cost-based optimizer
- **Adaptive Indexing**: Automatically create indexes based on query patterns

**Best Practices:**
- Increase cache size for read-heavy workloads
- Adjust parallel workers based on query complexity
- Enable adaptive indexing for unpredictable query patterns

### 2. Security Configuration

**Purpose:** Define authentication, authorization, and encryption policies.

**Key Settings:**
- **Encryption**: At-rest and in-transit encryption
- **Row-Level Security**: Tenant isolation at the row level
- **MFA**: Multi-factor authentication enforcement
- **IP Allowlisting**: Restrict access by IP address

**Best Practices:**
- Always enable encryption for sensitive data
- Use RLS for multi-tenant applications
- Enable MFA for production environments
- Maintain audit logs for compliance

### 3. Backup Configuration

**Purpose:** Ensure data durability and disaster recovery.

**Key Settings:**
- **Backup Frequency**: How often backups are created
- **Retention Period**: How long backups are kept
- **PITR**: Point-in-time recovery capability
- **Destinations**: Where backups are stored

**Best Practices:**
- Configure multiple backup destinations
- Enable PITR for critical data
- Encrypt all backups
- Test restore procedures regularly

### 4. Replication Configuration

**Purpose:** Provide high availability and disaster recovery across regions.

**Key Settings:**
- **Replication Mode**: Sync, async, or semi-sync
- **Target Regions**: Geographic regions for replicas
- **Consistency Level**: Trade-off between consistency and latency
- **Auto Failover**: Automatic promotion of replicas

**Best Practices:**
- Use async replication for global distribution
- Enable auto-failover for HA requirements
- Monitor replication lag
- Configure failover priority based on latency

### 5. Compliance Configuration

**Purpose:** Meet regulatory and compliance requirements.

**Key Settings:**
- **GDPR**: EU data protection regulation
- **HIPAA**: Health data compliance
- **SOC2**: Security controls certification
- **PCI-DSS**: Payment card data security
- **Data Residency**: Geographic data storage requirements

**Best Practices:**
- Enable required compliance features before storing data
- Configure retention policies for compliance
- Enable anonymization for personal data
- Document compliance configurations

---

## Validation Rules

### Global Constraints

1. **Cache Size**: Must not exceed 100 GB (100,000 MB)
2. **Parallel Workers**: Maximum 128 workers
3. **Password Complexity**: Must be between 1 and 5
4. **Backup Retention**: Must be >= PITR retention period

### Compliance-Driven Constraints

1. **HIPAA Compliance**:
   - Requires `encryption_at_rest = true`
   - Requires `enable_audit_log = true`
   - Requires `password_complexity >= 3`

2. **PCI-DSS Compliance**:
   - Requires `enable_audit_log = true`
   - Requires `encryption_at_rest = true`
   - Requires `audit_retention_days >= 90`

3. **GDPR Compliance**:
   - Requires `enable_rtbf = true` (right to be forgotten)
   - Requires `data_residency` includes EU for EU users
   - Requires `enable_anonymization = true` for personal data

---

## Examples

### Example 1: Update Performance Settings

```bash
curl -X PUT https://api.heliosdb.com/api/v1/tenants/550e8400-e29b-41d4-a716-446655440000/config \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "performance": {
      "cache_size_mb": 2048,
      "max_parallel_workers": 16,
      "enable_adaptive_indexing": true
    }
  }'
```

**Response:**
```json
{
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Successfully updated 3 configuration field(s)",
  "updated_fields": [
    "performance.cache_size_mb",
    "performance.max_parallel_workers",
    "performance.enable_adaptive_indexing"
  ],
  "updated_at": "2025-12-09T10:40:00Z"
}
```

### Example 2: Enable HIPAA Compliance

```bash
curl -X PUT https://api.heliosdb.com/api/v1/tenants/550e8400-e29b-41d4-a716-446655440000/config \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "security": {
      "encryption_at_rest": true,
      "enable_audit_log": true,
      "password_complexity": 4,
      "require_mfa": true
    },
    "compliance": {
      "hipaa": true
    }
  }'
```

### Example 3: Configure Multi-Region Replication

```bash
curl -X PUT https://api.heliosdb.com/api/v1/tenants/550e8400-e29b-41d4-a716-446655440000/config \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "replication": {
      "enabled": true,
      "mode": "async",
      "regions": ["us-east-1", "us-west-2", "eu-west-1"],
      "consistency_level": "eventual",
      "enable_auto_failover": true,
      "failover_priority": ["us-east-1", "us-west-2", "eu-west-1"]
    }
  }'
```

### Example 4: List Available Features

```bash
curl -X GET https://api.heliosdb.com/api/v1/tenants/550e8400-e29b-41d4-a716-446655440000/features \
  -H "Authorization: Bearer ${TOKEN}"
```

---

## Error Handling

### Common Error Codes

| Code | Description | Resolution |
|------|-------------|------------|
| 400 | Bad Request | Check validation errors in response |
| 401 | Unauthorized | Verify authentication token |
| 403 | Forbidden | Check tenant permissions |
| 404 | Not Found | Verify tenant ID exists |
| 409 | Conflict | Configuration violates constraints |
| 429 | Too Many Requests | Reduce request rate |
| 500 | Internal Server Error | Contact support |

### Error Response Format

```json
{
  "error": "Bad Request",
  "message": "Cache size exceeds maximum (100 GB)",
  "code": 400,
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

### Validation Error Examples

**Example 1: Exceeding Cache Limit**
```json
{
  "error": "Bad Request",
  "message": "Cache size exceeds maximum (100 GB)",
  "code": 400,
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

**Example 2: HIPAA Compliance Violation**
```json
{
  "error": "Bad Request",
  "message": "HIPAA compliance requires encryption at rest",
  "code": 400,
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

**Example 3: Invalid Password Complexity**
```json
{
  "error": "Bad Request",
  "message": "Password complexity must be between 1 and 5",
  "code": 400,
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

---

## Best Practices

### 1. Configuration Changes

- **Test First**: Test configuration changes in staging environments
- **Incremental Updates**: Make small, incremental configuration changes
- **Monitor Impact**: Monitor performance metrics after configuration changes
- **Document Changes**: Maintain a changelog of configuration modifications

### 2. Security Hardening

- Enable encryption at rest and in transit for all production tenants
- Require MFA for all administrative access
- Configure IP allowlists to restrict access
- Enable audit logging and review logs regularly
- Rotate encryption keys periodically

### 3. Performance Tuning

- Monitor query execution times and adjust workers accordingly
- Increase cache size for frequently accessed data
- Enable adaptive indexing for dynamic workloads
- Set appropriate query timeouts to prevent resource exhaustion

### 4. Compliance Management

- Enable required compliance features before storing regulated data
- Configure data residency restrictions for geographic compliance
- Enable retention policies and anonymization for personal data
- Document compliance configurations for audit purposes

---

## Rate Limits

- **Configuration Reads**: 100 requests/minute per tenant
- **Configuration Updates**: 10 requests/minute per tenant
- **Feature Queries**: 100 requests/minute per tenant

**Note**: Rate limits are subject to change based on tenant tier.

---

## Support

For questions or issues with the Tenant Configuration API:

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

---

**API Version**: v1.0.0