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.

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.

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¶

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

Compliance-Driven Constraints¶

HIPAA Compliance:
Requires encryption_at_rest = true
Requires enable_audit_log = true
Requires password_complexity >= 3
PCI-DSS Compliance:
Requires enable_audit_log = true
Requires encryption_at_rest = true
Requires audit_retention_days >= 90
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¶

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¶

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¶

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¶

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¶

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

Documentation: https://docs.heliosdb.com/api/configuration
Support: support@heliosdb.com
Status Page: https://status.heliosdb.com

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