CORS Configuration Reference
The CORS (Cross-Origin Resource Sharing) configuration is common across all services. This reference documents the configuration options for controlling cross-origin HTTP requests.
For a comprehensive understanding of CORS, see MDN’s CORS documentation.
Configuration Schema
Section titled “Configuration Schema”{ "cors": { "enabled": "boolean", "allowHeaders": "string[]", "allowMethods": "string[]", "credentials": "boolean", "exposeHeaders": "string[]", "maxAge": "number", "origin": "string[]" }}
Configuration Options
Section titled “Configuration Options”enabled
Section titled “enabled”- Type:
boolean
- Default:
false
- Description: Controls whether CORS is enabled for the service
allowHeaders
Section titled “allowHeaders”- Type:
string[]
- Default:
[]
- Description: List of non-standard HTTP headers that browsers are allowed to send
- Behavior:
- Applies to preflight requests and actual requests
- Supplements CORS-safelisted request headers
- Case-insensitive header matching
- CORS-safelisted headers (always allowed):
Accept
Accept-Language
Content-Language
Content-Type
(with restrictions)
- See:
Example configuration:
{ "cors": { "allowHeaders": ["Authorization", "X-Requested-With", "X-Custom-Header"] }}
Effect on response headers:
Access-Control-Allow-Headers: Authorization, X-Requested-With, X-Custom-Header
allowMethods
Section titled “allowMethods”- Type:
string[]
- Default:
["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]
- Description: HTTP methods allowed in CORS requests
- Allowed values: Based on HTTP/1.1 Method Definitions
GET
POST
PUT
PATCH
DELETE
OPTIONS
HEAD
- See: MDN: Access-Control-Allow-Methods
Example configuration:
{ "cors": { "allowMethods": ["GET", "POST", "OPTIONS"] }}
Effect on response headers:
Access-Control-Allow-Methods: GET, POST, OPTIONS
credentials
Section titled “credentials”- Type:
boolean
- Default:
false
- Description: Controls whether credentials (cookies, authorization headers) are allowed
- See: MDN: Access-Control-Allow-Credentials
Example configuration:
Note: When credentials
is true
, the Access-Control-Allow-Origin
header must be a specific origin (not *
), so origin
must be set accordingly.
{ "cors": { "credentials": true, "origin": ["https://app.example.com"] }}
Effect on response headers:
Access-Control-Allow-Credentials: trueAccess-Control-Allow-Origin: https://app.example.com
exposeHeaders
Section titled “exposeHeaders”- Type:
string[]
- Default:
[]
- Description: Response headers that browsers are allowed to access
- Behavior:
- Controls which response headers are visible to browser JavaScript
- Supplements CORS-safelisted response headers
- Case-insensitive header matching
- CORS-safelisted response headers (always exposed):
Cache-Control
Content-Language
Content-Length
Content-Type
Expires
Last-Modified
Pragma
- See:
Example configuration:
{ "cors": { "exposeHeaders": ["X-Request-ID", "X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset"] }}
Effect on response headers:
Access-Control-Expose-Headers: X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
maxAge
Section titled “maxAge”- Type:
number
- Default:
86400
- Description: Duration in seconds browsers should cache CORS preflight responses
- Unit: Seconds
- Valid range:
0
to86400
(24 hours) - See: MDN: Access-Control-Max-Age
Example configuration:
{ "cors": { "maxAge": 3600 // Cache preflight results for 1 hour }}
Effect on response headers:
Access-Control-Max-Age: 3600
origin
Section titled “origin”- Type:
string[]
- Default:
["*"]
- Description: List of allowed origins
- Format: Array of domain strings or
"*"
for all origins - See: MDN: Access-Control-Allow-Origin
Example configuration with wildcard:
{ "cors": { "origin": ["*"] }}
Effect on response headers:
Access-Control-Allow-Origin: *
Example configuration with specific origins:
{ "cors": { "origin": ["https://app.example.com", "https://admin.example.com"] }}
Effect on response headers (varies based on request origin):
Access-Control-Allow-Origin: https://app.example.comVary: Origin
Default Configuration
Section titled “Default Configuration”{ "cors": { "enabled": false, "origin": ["*"], "credentials": false, "allowMethods": ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"], "exposeHeaders": [], "allowHeaders": [], "maxAge": 86400 }}