API configuration (CORS, HSTS, Custom HTTP headers, Request filtering) – Checkbox Technology

Information

This guide explains how to configure the security settings for the Checkbox API ,including CORS, HTTP headers, HSTS, and path filtering. This feature is supported from version 8.20.0 of the Checkbox.

Configuration

The API security settings are configured in the appsettings.json file located in your API deployment directory (by default, it is checkbox/api-core).

CORS

"apiCors": {
  "origins": [
    "https://app.example1.com",
    "https://app.example2.com",
    "https://app.example3.com"
  ],
  "preflightMaxAge": 86400,
  "disabled": false,
  "allowedMethods": ["GET", "POST", "PUT"],
  "allowedHeaders": ["Content-Type", "Authorization", "X-Requested-With"],
  "allowCredentials": true
},

Property	Type	Default	Description
`origins`	string[]	`[]`	List of allowed origins. Empty array allows all origins (not recommended for production)
`preflightMaxAge`	int	`86400`	How long browsers can cache CORS preflight responses (in seconds)
`disabled`	bool	`false`	Disable CORS entirely
`allowedMethods`	string[]	`[]`	Specific HTTP methods to allow. Empty allows all methods
`allowedHeaders`	string[]	`[]`	Specific headers to allow. Empty allows all headers
`allowCredentials`	bool	`false`	Allow credentials (cookies, authorization headers) in CORS requests

HTTP Strict Transport Security forces HTTPS connections

  "apiHsts": {
    "disabled": false,
    "preload": false,
    "includeSubDomains": true,
    "maxAgeDays": 365
  }

Property	Type	Default	Description
`disabled`	bool	`false`	Disable HSTS
`preload`	bool	`false`	Include in browser preload lists
`includeSubDomains`	bool	`true`	Apply to all subdomains
`maxAgeDays`	int	`30`	How long browsers should remember HTTPS requirement

Add custom or remove HTTP headers.

  "apiHeaders": {
    "addCustom": {
      "X-Frame-Options": "DENY",
      "X-Content-Type-Options": "nosniff",
      "X-XSS-Protection": "1; mode=block",
      "Referrer-Policy": "strict-origin-when-cross-origin"
    },
    "remove": ["X-Powered-By", "X-AspNet-Version"]
  }

Property	Type	Default	Description
`addCustom`	Dictionary<string, string>	`{}`	Headers to add to responses
`remove`	string[]	`[]`	Headers to remove from responses

Path Filtering Configuration

  "apiPathFiltering": {
    "invalidCharacters": ["%", "..", ";"]
  }

Property	Type	Default	Description
`invalidCharacters`	string[]	`[]`	Characters/strings to block in URL paths

Considerations

Blocking is case-insensitive
May block legitimate requests (e.g., emails in URLs if blocking @)
Test thoroughly with your application's URL patterns

Applying Configuration Changes

Edit appsettings.json in your API deployment directory
Save the file
Restart the API website in IIS