#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

{
  "cors": {
    "enabled": boolean,
    "allowHeaders": string[],
    "allowMethods": string[],
    "credentials": boolean,
    "exposeHeaders": string[],
    "maxAge": number,
    "origin": string[]
  }
}

#Configuration Options

#enabled

• Type: boolean
• Default: false
• Description: Controls whether CORS is enabled for the service

#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:
  • MDN: Access-Control-Allow-Headers
  • Fetch Standard: CORS-safelisted request headers

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

• 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

• 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: true
Access-Control-Allow-Origin: https://app.example.com

#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:
  • MDN: Access-Control-Expose-Headers
  • Fetch Standard: CORS-safelisted response header

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

• Type: number
• Default: 86400
• Description: Duration in seconds browsers should cache CORS preflight responses
• Unit: Seconds
• Valid range: 0 to 86400 (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

• 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.com
Vary: Origin

#Default Configuration

{
    "cors": {
        "enabled": false,
        "origin": ["*"],
        "credentials": false,
        "allowMethods": ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
        "exposeHeaders": [],
        "allowHeaders": [],
        "maxAge": 86400
    }
}

#Additional Resources

• MDN: Cross-Origin Resource Sharing (CORS)
• W3C Fetch Standard: CORS Protocol
• HTTP Working Group: HTTP/1.1 Specification
• WHATWG: Fetch Standard