Configuration Guide¶

stdapi.ai is configured entirely through environment variables, which are read once at startup and cannot be changed without restarting the service. This guide explains each setting category with practical examples to help you configure the service correctly.

What you can configure:

• AWS regions - Access models across multiple regions for availability and model selection
• Data sovereignty - Control which AWS regions are used for compliance (GDPR, HIPAA, etc.)
• Storage - S3 buckets for file operations, regional buckets for multi-region deployments
• Authentication - API keys via SSM or Secrets Manager for secure access control
• Observability - Logging levels, OpenTelemetry, request/response debugging
• Security - CORS, proxy headers, trusted hosts for production deployments
• Performance - Caching, model overrides, S3 acceleration
• TLS / SSL - End-to-end encryption using Granian environment variables

Quick Start¶

For production deployments, configure these essential settings:

Minimal Production Setup¶

Single-region deployment with file storage only.

# S3 bucket for file storage (must be in same region as your server)
export AWS_S3_BUCKET=my-stdapi-bucket

# AWS_BEDROCK_REGIONS is optional - will auto-detect your current AWS region if not specified

Production with Authentication¶

Adds secure API key authentication via AWS Systems Manager.

# S3 bucket for file storage (must be in same region as your server)
export AWS_S3_BUCKET=my-stdapi-bucket

# Secure API authentication (recommended: SSM Parameter Store)
export API_KEY_SSM_PARAMETER=/stdapi/prod/api-key

# AWS_BEDROCK_REGIONS is optional - will auto-detect your current AWS region if not specified

Full Production Setup (All Features Enabled)¶

Multi-region deployment with all AWS AI services, observability, and security features.

# Core AWS configuration - host server in first region
export AWS_BEDROCK_REGIONS=us-east-1,us-west-2,eu-west-1

# S3 bucket for file storage (must be in us-east-1, your first/primary region)
export AWS_S3_BUCKET=my-stdapi-us-east-1-bucket

# Optional: Transcribe S3 bucket (defaults to AWS_S3_BUCKET if not specified)
# Only set this if you need a separate bucket or if transcribe is in a different region
# export AWS_TRANSCRIBE_S3_BUCKET=my-stdapi-transcribe-us-east-1

# Optional: Regional buckets for async/batch inference in other regions
export AWS_S3_REGIONAL_BUCKETS='{"us-west-2": "my-stdapi-us-west-2-bucket", "eu-west-1": "my-stdapi-eu-west-1-bucket"}'

# AWS AI services regions (optional - when unset, every AWS_BEDROCK_REGIONS entry is a
# candidate with automatic failover; set one to pin the service to a single region)
export AWS_POLLY_REGION=us-east-1           # Text-to-speech
export AWS_TRANSCRIBE_REGION=us-east-1      # Speech-to-text (audio transcription)
export AWS_COMPREHEND_REGION=us-east-1      # Language detection & moderation
export AWS_TRANSLATE_REGION=us-east-1       # Text translation

# Authentication
export API_KEY_SSM_PARAMETER=/stdapi/prod/api-key

# Logging
export LOG_LEVEL=warning
export LOG_CLIENT_IP=true

# Optional: OpenTelemetry observability (AWS X-Ray integration)
# export OTEL_ENABLED=true
# export OTEL_SERVICE_NAME=stdapi-production
# export OTEL_SAMPLE_RATE=0.1

# Production security settings (when behind AWS ALB/CloudFront)
export ENABLE_PROXY_HEADERS=true

# Note: TRUSTED_HOSTS not recommended with AWS ALB - use ALB host-based routing instead
# Only use TRUSTED_HOSTS if you cannot configure host validation at the load balancer level

# Optional: CORS for browser-based web applications
# export CORS_ALLOW_ORIGINS='["https://app.example.com"]'

Development Setup¶

Local development configuration with API documentation and debug logging enabled.

# Minimal configuration for local development
export AWS_S3_BUCKET=my-stdapi-dev-bucket

# Enable API documentation
export ENABLE_DOCS=true
export ENABLE_REDOC=true

# Full request/response logging for debugging
export LOG_LEVEL=info
export LOG_REQUEST_PARAMS=true

# AWS_BEDROCK_REGIONS is optional - will auto-detect your current AWS region if not specified

What to Set¶

Most deployments set two variables. The official Terraform module sets both for you. Everything else has a working default; each tier below tells you when to leave that default behind.

Two flags mark the rows to read in full before setting them: security changes who can reach the API or what a caller may do, cost adds or changes an AWS bill line.

Tier 1 — Set these (2)¶

Tier 2 — Common (about 20)¶

Tier 3 — Everything else¶

Grouped by page. The defaults work; open a page when a Tier 1 or Tier 2 row above sends you there, or when the reason in the last column is yours.

Configuration Order¶

When deploying stdapi.ai, configure settings in this recommended order:

1. IAM Permissions - Set up AWS access first
2. AWS Services and Regions - Choose the Bedrock regions that serve your models, and how requests fail over between them
3. Storage - Point file, image, video, batch and vector store features at their S3 buckets
4. Authentication - Secure your API with authentication
5. Optional features - Add observability, the Bedrock features such as guardrails, and model routing as needed

IAM Permissions¶

Every AWS permission the gateway needs is on the IAM Permissions page: the Amazon Bedrock statements every deployment requires, then one section per optional feature — S3 file storage, vector stores, the shared table, speech, translation, cost tracking, the Usage API, tenant keys — each listing the exact actions and resources it adds. It ends with copy-ready complete policy examples and the AWS tag policy requirements. Go there to write the role your deployment runs under, or when a feature returns an access-denied error.

Deprecated Settings¶

Next Steps¶