Skip to content
HeliosDB Full

Tenant Configuration API Documentation

Tenant Configuration API Documentation

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

GET /tenants/{id}/config

Retrieves the complete configuration for a tenant.

Request

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):

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

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):

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

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):

{
  "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.

FieldTypeDescriptionRange/ValuesDefault
cache_size_mbintegerResult cache size in MB0-1000001024
max_parallel_workersintegerMaximum parallel query workers1-1288
enable_query_optimizationbooleanEnable query optimizertrue/falsetrue
enable_result_cachingbooleanEnable result cachingtrue/falsetrue
enable_adaptive_indexingbooleanEnable adaptive indexingtrue/falsetrue
query_timeout_secsintegerQuery timeout in seconds1-3600300
query_memory_limit_mbintegerPer-query memory limit in MB256-655364096
collect_query_statsbooleanCollect query statisticstrue/falsetrue

SecurityConfig

Defines security and access control policies.

FieldTypeDescriptionRange/ValuesDefault
encryption_at_restbooleanEnable encryption at resttrue/falsetrue
encryption_in_transitbooleanEnable encryption in transittrue/falsetrue
encryption_algorithmstringEncryption algorithm”AES-256-GCM”, “AES-128-GCM""AES-256-GCM”
kms_key_idstringKMS key identifierValid KMS ARNnull
enable_rlsbooleanEnable row-level securitytrue/falsetrue
enable_column_encryptionbooleanEnable column encryptiontrue/falsefalse
password_complexityintegerPassword complexity level1-53
session_timeout_minsintegerSession timeout in minutes5-144030
require_mfabooleanRequire multi-factor authtrue/falsefalse
allowed_ipsarray[string]Allowed IP addresses (CIDR)Valid CIDR notation[]
enable_audit_logbooleanEnable audit loggingtrue/falsetrue
audit_retention_daysintegerAudit log retention days1-365090

BackupConfig

Configures backup policies and schedules.

FieldTypeDescriptionRange/ValuesDefault
enabledbooleanEnable automatic backupstrue/falsetrue
frequency_hoursintegerBackup frequency in hours1-16824
retention_daysintegerBackup retention days1-36530
full_backup_intervalintegerFull backup interval (incrementals)1-307
destinationsarrayBackup destinationsBackupDestination[][]
enable_pitrbooleanEnable point-in-time recoverytrue/falsetrue
pitr_retention_daysintegerPITR retention days1-307
encrypt_backupsbooleanEncrypt backup datatrue/falsetrue
compress_backupsbooleanCompress backup datatrue/falsetrue

ReplicationConfig

Manages multi-region replication settings.

FieldTypeDescriptionRange/ValuesDefault
enabledbooleanEnable replicationtrue/falsefalse
modestringReplication mode”async”, “sync”, “semi-sync""async”
regionsarray[string]Target regionsAWS regions[]
consistency_levelstringConsistency level”eventual”, “read_after_write”, “strong""eventual”
max_lag_secondsintegerMax replication lag (seconds)1-30060
enable_auto_failoverbooleanEnable automatic failovertrue/falsetrue
failover_priorityarray[string]Failover priority orderRegion names[]

ComplianceConfig

Configures compliance and regulatory requirements.

FieldTypeDescriptionRange/ValuesDefault
gdprbooleanEnable GDPR compliancetrue/falsefalse
hipaabooleanEnable HIPAA compliancetrue/falsefalse
soc2booleanEnable SOC2 compliancetrue/falsefalse
pci_dssbooleanEnable PCI-DSS compliancetrue/falsefalse
data_residencyarray[string]Data residency requirementsCountry codes[]
enable_retention_policiesbooleanEnable retention policiestrue/falsefalse
default_retention_daysintegerDefault retention period1-3650365
enable_anonymizationbooleanEnable data anonymizationtrue/falsefalse
enable_rtbfbooleanEnable right-to-be-forgottentrue/falsefalse

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

Terminal window
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:

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

Terminal window
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

Terminal window
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

Terminal window
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

CodeDescriptionResolution
400Bad RequestCheck validation errors in response
401UnauthorizedVerify authentication token
403ForbiddenCheck tenant permissions
404Not FoundVerify tenant ID exists
409ConflictConfiguration violates constraints
429Too Many RequestsReduce request rate
500Internal Server ErrorContact support

Error Response Format

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

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

Example 2: HIPAA Compliance Violation

{
  "error": "Bad Request",
  "message": "HIPAA compliance requires encryption at rest",
  "code": 400,
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000"
}

Example 3: Invalid Password Complexity

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

Last Updated: 2025-12-09 API Version: v1.0.0