Authentication & Security¶

stdapi.ai provides flexible authentication options and built-in security mechanisms to protect your API. Choose from API key authentication for simple deployments to enterprise-grade identity management via AWS services — all backed by built-in SSRF protection, host header validation, and configurable encryption in transit.

Authentication Methods¶

API Key Authentication¶

The API key authentication method uses a single API key that mimics the behavior of upstream OpenAI and Anthropic authentication. It must be provided by clients in the Authorization: Bearer <key> or X-API-Key header.

Three mutually exclusive sources are supported — configure exactly one:

• SSM Parameter Store (API_KEY_SSM_PARAMETER) — the parameter must already exist before startup.
• Secrets Manager (API_KEY_SECRETSMANAGER_SECRET) — the secret must already exist; supports a configurable key within the JSON secret via API_KEY_SECRETSMANAGER_KEY.
• Direct value (API_KEY) — for local development and testing only; not recommended for production.

For the full list of environment variables and required IAM permissions for each method, see the Configuration Guide.

OIDC, Cognito & IAM Identity Center¶

For user-facing applications or enterprise SSO, you can offload authentication to an OpenID Connect (OIDC) provider, Amazon Cognito, or AWS IAM Identity Center (the AWS-native workforce SSO service for centralised employee and partner access).

When authentication is handled at this layer, requests are fully validated before they reach stdapi.ai — the application receives only authenticated, pre-authorised requests.

via Application Load Balancer (ALB)¶

The AWS ALB can authenticate users before forwarding requests to stdapi.ai. This is the most common way to add OIDC or Cognito authentication.

• Capabilities: Integrates with any OIDC-compliant identity provider — including AWS IAM Identity Center (workforce SSO), Amazon Cognito User Pools, or third-party providers such as Okta, Auth0, and Google.
• IAM Identity Center: Expose the Identity Center OIDC application endpoints as the ALB OIDC configuration. This gives employees and partners seamless SSO using their AWS-managed identity, with support for MFA and permission sets defined in your AWS Organization.
• Documentation: Authenticate users using an Application Load Balancer

via API Gateway¶

Both REST and HTTP APIs support OIDC and Cognito integration.

• HTTP API (JWT): Native support for JWT-based authorization — any OIDC provider (including IAM Identity Center configured as a trusted token issuer) can be used.
  • Controlling access to HTTP APIs with JWT
• REST API: Supports Cognito User Pool authorizers and Lambda Authorizers for custom authentication logic.
  • Control access to a REST API in API Gateway

AWS IAM¶

For service-to-service communication within AWS or when using IAM roles for access control, you can use AWS IAM authentication via API Gateway. Clients sign their requests using the AWS Signature Version 4 (SigV4) process, enabling fine-grained access control using IAM policies attached to users or roles.

via API Gateway¶

Amazon API Gateway provides native IAM authentication for both REST and HTTP APIs.

• Documentation:
  • IAM authorization for REST APIs
  • IAM authorization for HTTP APIs

No Authentication¶

In certain environments, you may choose to disable application-level authentication and rely entirely on network security.

When to Use¶

• Local development or testing using Docker.
• Internal VPC deployments where traffic is trusted.
• When an upstream proxy handles all security and identity.

Configuration¶

To disable API key authentication, do not configure any API key environment variables (API_KEY, API_KEY_SSM_PARAMETER, or API_KEY_SECRETSMANAGER_SECRET).

When no API key authentication is configured, stdapi.ai will:

1. Accept all incoming requests without validating an API key.
2. Log a security warning at startup.

Application Security¶

stdapi.ai includes built-in security mechanisms that are active regardless of the authentication method chosen.

SSRF Protection¶

Users can pass URLs to the API as multimodal content references (images, documents, audio). The application fetches the content at those URLs before forwarding it to the model. Without protection, a malicious user could supply URLs pointing to internal services — such as the AWS EC2/ECS metadata endpoint or private network resources — and read sensitive data through the model response.

stdapi.ai validates every user-supplied URL via DNS resolution before fetching its content — each hostname is resolved and every resulting IP is checked against the blocklist. This protects against DNS rebinding attacks where a seemingly-safe domain resolves to a blocked address.

• Baseline Protection: Always-active blocking of loopback (127.0.0.1, localhost), link-local (169.254.169.254), and reserved address ranges. This prevents access to the AWS EC2/ECS metadata service from within the container.
• Private Network Blocking: By default, the service also blocks all RFC 1918 private networks (10.x.x.x, 172.16.x.x, 192.168.x.x). Disable only in controlled environments where accessing local networks is required (SSRF_PROTECTION_BLOCK_PRIVATE_NETWORKS=false).
• Defense in Depth: Even with SSRF protection enabled, restrict outbound Security Group rules to only the necessary AWS service endpoints.

Host Header Validation¶

To protect against Host header injection and web cache poisoning, stdapi.ai can validate the Host header of incoming requests. When TRUSTED_HOSTS is not configured, no Host header validation is performed.

• Recommended Approach: Use AWS ALB host-based routing rules to reject invalid Host headers before they reach the application. This is more performant and centrally managed.
• Application Validation: Use TRUSTED_HOSTS to define a list of approved hostnames (supports wildcards like *.example.com). Requests with non-matching headers are rejected with an HTTP 400 error.

Browser Security (CORS)¶

If your API is accessed directly from web browsers, Cross-Origin Resource Sharing (CORS) must be configured to prevent unauthorized cross-site requests. When CORS_ALLOW_ORIGINS is not configured, the CORS middleware is not enabled and browser cross-origin requests are blocked by default.

• Principle of Least Privilege: Only allow specific, trusted domains using CORS_ALLOW_ORIGINS.
• Offload to Infrastructure: For production, consider managing CORS at the AWS ALB or API Gateway level for better performance and to keep your application logic clean.

Proxy Headers¶

When running behind a load balancer (ALB) or reverse proxy, stdapi.ai can be configured to trust X-Forwarded-* headers (X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Port) to correctly identify the original client IP and protocol. When enabled, the real client IP appears in request logs instead of the proxy's IP.

• Security Warning: Only enable ENABLE_PROXY_HEADERS when the service is deployed behind a trusted proxy. Enabling this in a publicly exposed environment without a proxy allows attackers to spoof their IP address by sending custom headers.

Security Best Practices¶

Network Isolation:

• Deploy in private subnets — without direct internet access.
• Restrict security group inbound rules — allow traffic to the stdapi.ai service only from the ALB or API Gateway security group on the application port.
• Apply strict egress rules — limit outbound traffic to only the required AWS services (Bedrock, S3, etc.).
• Use VPC endpoints — set vpc_endpoints_allowed=true (the default) to keep all traffic to Bedrock, S3, SSM, CloudWatch Logs, and AI services off the public internet.

WAF & Rate Limiting:

• Enable AWS WAF — the Terraform module supports WAF via alb_waf_enabled=true. When enabled, it activates the AWS Managed Core Rule Set (SQLi, XSS, common exploits), Linux Rule Set, and IP Reputation List (known malicious IPs).
• Configure rate limiting — set alb_waf_rate_limit to limit the number of requests per IP per 5-minute window, protecting against abuse and quota exhaustion.
• Block anonymous IPs — set alb_waf_block_anonymous_ips=true to block known VPNs, open proxies, and Tor exit nodes.

Secrets Management:

• Use SSM Parameter Store or Secrets Manager — always use encrypted secret storage for production API keys; never pass keys as plain environment variables.
• Rotate API keys — Secrets Manager supports automated secret rotation via Lambda; note that stdapi.ai reads the key once at startup, so a container restart is required after rotation.

IAM & Access Control:

• Apply least-privilege IAM permissions — ensure the ECS Task Role has only the required permissions needed for operation.

Encryption in Transit¶

To ensure data protection during transmission, stdapi.ai supports several encryption-in-transit configurations.

Standard¶

This is the default configuration when no additional encryption settings are applied. TLS is terminated at the entry point (ALB or API Gateway). Traffic between the entry point and the stdapi.ai service travels over HTTP within the private VPC, secured by mandatory Security Group rules. This is the most common configuration for AWS deployments.

End-to-End¶

If your compliance requirements mandate encryption all the way to the container, you can enable TLS between the load balancer and the container.

• Native Support: The provided container images run Granian natively. TLS can be enabled directly by setting the following Granian environment variables:
  • GRANIAN_SSL_CERTIFICATE: Path to the SSL certificate file (e.g., /etc/ssl/certs/server.crt).
  • GRANIAN_SSL_KEYFILE: Path to the SSL private key file (PKCS#8 format only, e.g., /etc/ssl/private/server.key).
  • GRANIAN_SSL_KEYFILE_PASSWORD: (Optional) Password for the private key file.
  • GRANIAN_SSL_PROTOCOL_MIN: (Optional) Minimum supported TLS version — tls1.2 or tls1.3 (defaults to tls1.3).
• Mutual TLS — Container: As an advanced form of end-to-end encryption, you can also require the upstream caller (e.g., the ALB) to present a certificate to the container.
  • GRANIAN_SSL_CA: Path to the CA certificate bundle used to verify client certificates.
  • GRANIAN_SSL_CLIENT_VERIFY: Set to true to enable client certificate verification.
• ECS Certificate Mounting: When running on AWS ECS, certificate and key files must be mounted into the container. This is typically achieved using Amazon EFS volumes or by baking the certificates into a custom image (not recommended for secrets).
• Certificate Management: Use ACM Private CA or a self-signed certificate for the internal service. Note that the ALB does not validate the backend certificate by default; it only ensures the connection is encrypted.
• Sidecar Proxy: Alternatively, you can run a sidecar container (like Nginx or Envoy) alongside stdapi.ai to handle TLS termination locally.

Mutual TLS — Client to Entry Point¶

For environments requiring mutual authentication between the final client and the entry point:

• Offloaded mTLS: mTLS can be enabled at the ALB (using Application Load Balancer Mutual TLS) or API Gateway (using Mutual TLS authentication). In this setup, the entry point validates the client certificate before forwarding the request.
• Service Mesh / Sidecar: You can implement mTLS between internal services using a Service Mesh (like AWS App Mesh) or by using a sidecar proxy (like Envoy) that manages certificate rotation and verification.

Next Steps¶