Configuring cross-origin resource sharing (CORS) for the Pega API

Cross-origin resource sharing (CORS) settings in Pega Platform enable you to control and secure the use of the Pega API services embedded in your web or mobile client application. Configure these settings to permit Pega API access across domains that you trust using the headers that you specify. You can also use these settings to control the time period between preflight requests.

When a web browser attempts to access a remote Pega API service, it sends a preflight request (an OPTIONS method call) to the Pega Platform application server. After the successful completion of the preflight request, the browser sends the actual request to the Pega API service.

Set the values of three Dynamic System Settings instances to configure CORS for the Pega API.

  1. In the navigation panel, click Records > SysAdmin > Dynamic System Settings.
  2. Search for Setting Purpose containing "CORS".
    Tip: Use the search bar to find any settings rule quickly.
  3. Enter the values for the following instances:
    • Pega-API.api.v1.CORS.allowedheaders: Enter a comma-separated list of allowed request header values. The authorization and content-type headers are required for Pega Platform applications. The default value is: authorization, content-type
    • Pega-API.api.v1.CORS.allowedorigins: Enter a comma-separated list of domains (origins) that are allowed to access the Pega API services. The system evaluates all origins that you enter for this setting, until it finds a match for the origin header of the request. Wildcard characters are supported, as shown in these sample values. The default value is: *
      • "www.abc.com" allows requests from this specific host.
      • "*.abc.com" allows requests from any site hosted in the abc.com domain.
      • "*" allows requests from any website. Use this value only if you want to give public access to the Pega API services.
      • Null (blank field) does not allow any remote host access requests.
      Note: The actual value of the Access-Control-Allow-Origin header returned in the response, is the full name of the host that sends the request. For example, if you save "*.abc. com" as the allowed origin and mysite.abc.com sends a request, the actual value of the Access-Control-Allow-Origin response header is "mysite.abc.com", and not "*.abc.com".
    • Pega-API.api.v1.CORS.maxage: Enter the time period (in seconds) to cache the response to a preflight request. This is the time period between two consecutive preflight requests, within which you do not want the web browser to send a new preflight request. A longer period reduces the frequency of browser preflight OPTIONS method call requests. The default value is: 600

      For example, a web browser sends a preflight request to the Pega API GET /cases service, 300 seconds after accessing the GET /assignments service.

      • If you set the maxage to "400", the browser does not send another preflight request for the GET /cases service.
      • If you set the maxage to "200", the browser sends a a preflight request for the GET /cases service.