Overview
The StackPath API is a tool that exposes all of our available settings that you can use to customize your sites' settings, including the more advanced ones that are not shown in the StackPath Control Portal.
StackPath's Site Configuration Editor takes these advanced settings and exposes them in the StackPath Control Portal, creating a simpler experience by eliminating the need to use our API.
You can use this document to learn how to use StackPath's Site Configuration Editor to manage your site's more complex settings.
Accessing the Site Configuration Editor
To access the Site Configuration Editor:
- In the StackPath Control Portal, in the left-side navigation, click Sites.
- Locate and select the desired site.
- In the left-side navigation, under Sites, click Settings.
- Click Site Configuration.
When you have reviewed and updated all of your configuration settings, be sure to click the Publish button that appears on the right.
Use the navigation on the right to jump to a specific section on this page.
User Access Restrictions
You can use the User Access Restrictions (Security) feature to control who can view or share your content based on an IP address or geographic location, and/or by the website linking to your content.
This section contains the following features:
- Geographic Restrictions
- IP Address Restrictions
- Referrer Restrictions
- User Access Override
Geographic Restrictions
You can use this feature to explicitly allow users to access your content based on the country where they are requesting from.
This feature is commonly used by streaming video providers who want to restrict access to their content in particular markets, which is also known as geo-blocking.
To use this feature, you must enter a value (or region code) that is specific to the region that you want to target.
- You must enter values that are supported by the MaxMind® GeoIP database.
- Mark Enable to activate the customizable fields.
- Under Region Type, select a region code to use.
- Most users restrict content based on a country code.
- Under Region Codes, enter the code that corresponds to the Region Type you selected. In short, enter the list of regions that will be allowed to access the content.
- To better understand how to enter this information, review the following articles:
- Click + Add Exception to add another exception.
IP Address Restrictions
You can use this section to explicitly allow or deny access to content based on a customizable list of IP addresses.
- Mark Enable to activate the customizable fields.
- Under Access Directive, select Allow or Deny.
- Under IP List, enter the list of IP addresses that you want to allow or deny access to the content.
- Review the optional features, and then click + Add Exception.
Referrer Restrictions
You can use this feature to restrict access to content based on a customizable list of websites or domains or referrers.
When you use this feature, you can prevent your content from being distributed by unauthorized websites using hotlinking or deep linking methods. Websites that are not listed in this policy will be denied access to the content cached at this location.
- Mark Enable to activate the customizable fields.
- Under Authorized Domains, enter the list of websites to allow access to the content.
- Click the plus ( + ) icon.
User Access Override
You can use this feature to override existing restrictions and allow specific traffic to access your content.
For example, if you used the Geographic Restrictions section to restrict access to a certain Geography, then you can use this User Access Override section to make a special rule and allow a specific IP address to access your content.
You can configure IP addresses and IP CIDR blocks.
The configurations on this section will override current restrictions in the Geographic Restrictions, the IP Address Restrictions, and the Referrer Restrictions sections.
While you can enter a non-routable IP address, it will be filtered from the list. Review the following list of non-routable IP addresses:
- 10.0.0.0/8 IP addresses: 10.0.0.0 – 10.255.255.255
- 172.16.0.0/12 IP addresses: 172.16.0.0 – 172.31.255.255
- 192.168.0.0/16 IP addresses: 192.168.0.0 – 192.168.255.255
- IPv6: fc00::/7
Content Access Authentication
You can use the Content Access Authentication (Security) feature to require authentication to access the content.
Review the following options:
| Option | Description |
| URL Signing |
URL Signing allows you to protect files from unauthorized access with an encrypted key. To learn more, see URL Signing. |
| Passphrase | The shared secret is used during the signing process. It should only be known by StackPath and systems authorized to sign your content. |
| Passphrase Name | The name of the portion of the URL that contains the Passphrase. It's only used during the generation and validation of a URL, and shouldn't be present in the published URL. |
| URL Signature Name | The name of the portion of the URL that's used to identify the signature for the URL. |
| Expiration Name | The name of the query string parameter that contains the epoch time after which the URL is considered invalid. |
| IP Address Whitelist | Limit access to the URL to a specific IP address or set of IP addresses. |
|
URL Signature Path Length |
The number of characters in the path that should be considered when validating the URL signature. |
| Basic Authentication |
Basic Authentication allows you to require authentication in the form of a username and password from within an HTTP user agent, or web browser. Basic Authentication is a simple method of authentication that allows an HTTP user agent, such as a web browser, to provide a user name and password when making a request for content. |
| Binding Point URL | The URL authentication is sent to in order to see if it's valid. |
| Realm | The name of the pop-up window that prompts for the user name and password. |
|
Authentication TTL |
The time in seconds that the authentication session will be cached by browsers. |
URL Signing
You can use this feature to prevent the free distribution of content outside of your designated workflow. Access is denied when a user tampers with the URL or if a well-formatted URL has an expired timestamp.
URL signing is based on the concept of building a URL that contains a shared secret, a passphrase that is only known to the signer and the CDN.
The URL is initially constructed with the passphrase (and optional fields, such as TTL) included, the URL is hashed using the MD5 algorithm, and then the passphrase field is removed and the result of the MD5 is added. The resulting URL can then be used on the public Internet, in clear text, without exposing the secret passphrase.
Any attempt to alter the resulting URL will also result in the value of the MD5 hash changing, and invalidating the URL (any attempt to also alter the MD5 hash will similarly fail, as the shared secret is not available in order to generate the new correct hash).
When the request arrives at StackPath, the same process is followed (we also have the shared secret, per the inputs to the URL signing rule on the Content Protection policy). If our hash matches the URL's hash, then we know that whoever signed the URL knew the shared secret at that time. If any optional fields are included, they are also validated.
Cache Settings
You can use Cache Settings (Cache) to set how and when assets stored on a particular scope in the CDN cache should be purged and replaced with new content from the origin.
When you properly configure how and when new content is stored in the CDN cache, you help enhance the delivery of your content to your end-users. When you configure how the CDN caches your content, you help reduce the stress of unnecessary requests placed on your origin.
Review the following cache features:
- Browser caching
- CDN caching
- Stale cache extension
Browser Caching
You can use Browser Caching to cache content in a variety of ways.
Specifically, you can:
- Use the Synchronize Browser and CDN TTLs to sync with the end user's browser to match its own cache TTL to the amount of time remaining before the CDN TTL expires. In short, this feature offers a pro-rated TTL based on the length of time remaining before the CDN TTL expires.
- Use Browser TTL to control how long content can be cached by the end user's browser, independently of how long that content is cached on the CDN.
CDN Caching lets you define how and when content stored specifically in the CDN cache expires and is replaced with new content from your Origin.
By default, when a new Site is created, the Cache Expiration Method will be set to Origin Controlled.
Stale Cache Extension
You can use Stale Cache Extension to instruct the CDN on how to handle stale content.
Specifically, you can:
- Use Stale Cache Retry Timer to troubleshoot when your origin is unreachable. You can set a time in seconds to determine how often the CDN should attempt to establish a new connection.
- Use Maximum Stale File TTL to troubleshoot when your origin is not responsive. You can set a time in seconds to determine how long the CDN should keep stale content cached.
- The CDN will continue to attempt a connection to the origin, based on the configuration in Stale Cache Retry Timer.
-
If your origin fails to respond after the time set by the Maximum Stale File TTL, then the CDN will stop attempting to connect to your origin, will stop delivering stale content, and the end-user will receive an error message.
Cache Keys
You can use Cache Keys (Cache) to cache additional versions of a file.
Use Cache Key Modification to configure how the cache distinctly stores assets.
Use Dynamic File Versioning to specify which parts of the end-user's request should be used to build additional cache keys. Different parameters or headers will cause different versions of a file to be cached.
Specifically, you can use the following features:
- Use Additional Cache Keys By Headers to compile a list of headers to use as independent cache keys.
- Use Additional Cache Keys by Query String Parameters to compile a list of query string parameters to use as additional cache keys.
Please note that negative pattern matching is not supported.
Custom Client Identification
You can use the Custom Client Identification (Origin) feature to override certain headers sent to the origin from the CDN.
Specifically, you can use the following features:
- Use Basic Authorization X-Forwarded-For Header to enter the name of X-Forwarded-For header that the CDN will use when making requests to your basic authorization server.
- Use Origin Server X-Forwarded-For Header to enter the name of the X-Forwarded-For header that the CDN will use when making requests to your origin.
Origin Selection
You can use the Origin Selection (Origin) feature to define how your origin interacts with the CDN.
Specifically, you can use the following features:
- Use Compressed Origin Pull to enable the CDN to request and accept Gzipped content from the origin. The CDN caching servers send your Origin the HTTP Access-Encoding header with the GZip code: Accept-Encoding: gzip
- Use Origin Persistent Connection to enable persistent connections to the origin.
- Use Origin Pull Settings to control the behavior of origin pull requests. Specifically, you can use:
- No Query String Parameters to remove all query strings from requests sent to the origin.
- Origin Redirect Behavior to proxy redirects to the client, or follow them immediately from the CDN.
- Retry Methods to create a list of HTTP methods to define types of origin pull requests that should be retried if requests to the origin fail.
- Use Origin Pull Protocol to configure whether the CDN should use secured or non-secured connections when communicating with the origin. Specifically, you can use:
- Enable SNI Origin Pull to have the CDN use SNI when making a secured connection to the origin.
- Origin Pull Protocol to have the CDN request assets from the origin as HTTP only, HTTPS only, or by matching the request protocol.
- Use Origin Connections to define the origin that the CDN should use to populate the cache. Specifically, you can use:
- Primary Origin to set the first origin that the CDN will use to populate the cache.
- Backup Origin to set the failover origin, in case the primary origin cannot be reached.
- Base Path to specify the path on your origin that contains the content to cache on the site. The path that you enter will append to the hostname of your primary and backup origin when content is requested.
Origin Load Reduction
You can use the Origin Load Reduction (Origin) feature to reduce the bandwidth or number of connections from the origin.
Specifically, you can use the following feature:
- Use Download and Store Files in Segments to download and store files in small parts rather than as a whole, and potentially large assets.
Bandwidth Rate Limiting
You can use Bandwidth Rate Limiting (Delivery) to set the rate at which files are transferred in order to optimize bandwidth usage on your account and reduce associated costs.
With Bandwidth Rate Limiting, you can reduce your bandwidth costs by limiting the rate at which media files and streaming media are transferred to consumers that may decide to abort a download or quit streaming midway through the data transfer.
Specifically, you can use the following features:
- Use Bandwidth Rate Limiting to limit the transfer rate of files in general. Specifically, you can use:
- Burst Units to specify units to be used for the burst rate. By default
kbpsis used. - Sustained Units to specify units to be used for the sustained rate. By default
kbpsare used. - Burst Rate Limit Query String Name to enter the name of the query string parameter that establishes the initial burst rate to use when delivering content.
- Sustained Rate Limit Query String Name to enter the name of the query string parameter that establishes the sustained rate to use when delivering content.
- Burst Units to specify units to be used for the burst rate. By default
- Use Pattern Based Bandwidth Rate Limiting to limit the transfer rate of files by extension. For example, you could limit the transfer of
.mp4to1mbps. Specifically, you can use:- Limit based on File Extension to indicate the files by extension that you would like to apply Bandwidth Limiting to. You may add or remove any file extension you want to target with the policy. All extensions specified apply to all web browsers. You can target any media file extension, such as
.mp4; .zip; .mp3. - Rate Limit to indicate the sustained rate at which you want files to transfer, such as
1mbps.
- Limit based on File Extension to indicate the files by extension that you would like to apply Bandwidth Limiting to. You may add or remove any file extension you want to target with the policy. All extensions specified apply to all web browsers. You can target any media file extension, such as
Dynamic Files
You can use the Dynamic Files (Delivery) feature to set and define a variety of configurations that help search engines discover and index your content.
Specifically, you can use the following features:
- Use Robots.txt Configuration to define how the CDN delivers the Robots.txt file.
- In Robots.txt File, enter or paste the contents of the Robots.txt file that the CDN should deliver (instead of the default). The robots.txt file is used to instruct web crawlers and search engine robots on how to crawl pages on your website. In other words, the text file tells all or specific web crawlers if they are allowed (or not allowed) to crawl and index certain pages of your website.
- Use Robots.txt Cache-Control Header to define the Cache-Control header that the CDN will deliver with the Robots.txt file.
Content Compression
You can use Content Compression (Delivery) to deliver compressed versions of files to end-users in order to increase the performance of your website.
Specifically, you can use the following feature:
- Use GZip Compression to increase the speed of your website or web apps by compressing certain files before they are delivered to your users. GZip Compression is a standard practice which allows you to make websites and web apps load faster by making files smaller. When text files like HTML and JavaScript are targeted for compression, page load times go down, and the bandwidth required to transfer those files decreases. Some older versions of browsers do not support compression. In those situations, the CDN will deliver uncompressed file versions. While most files can be compressed, certain files, such as text files, will be compressed more effectively than others. In other cases, files like .zip files which are already compressed may actually become larger when GZipped due to the file’s receiving GZip metadata. Specifically, you can use:
- Gzip Compression Level
- Gzip File Extensions to specify which files should be Gzipped by file extension. The caching servers will use this list to identify the content you want compressed.
- Gzip Mime-types to specify which files should be Gzipped by mime-type. The caching servers will use this list to identify the content you want compressed.
Force Downloads
You can use the Force Downloads (Delivery) feature to enable the automatic download of assets delivered to your users by forcing assets to download instead of opening in the browser.
Specifically, you can use the following features:
- Use Content Disposition by HTTP Header to control the Content-Disposition header on the responses from your origin using a pattern matched against the value of any HTTP header present in an end-user's request for content. Specifically, you can use:
- Values to Download to create a list of file extensions to use in determining which files are forced to download.
- Header to Use to specify the name of the HTTP header to use in the HTTP header pattern match.
- Override Origin Content Disposition to allow the CDN-generated Content-Disposition header to override the header from your origin.
- Set Content Disposition to select a type of Content-Disposition header, attachment, or inline.
- Use Content Disposition By URL to control the Content-Disposition header on the response from your origin via the request URL of your end-users. In other words, the URL that your end-users use to access a file can determine if the file is forced to download (or not download). Specifically, you can use:
- Query String File Name is the query string parameter name that specifies the filename used in the Content-Disposition header.
- Query String for Content Disposition to specify the type used in the Content-Disposition header, attachment, or inline.
- Override Origin Content Disposition to allow the CDN-generated Content-Disposition header to override the header from your origin.
- Query String for Override to override the whole value in the Content-Disposition header with a query string parameter name. If present in the request URL, Query String for File Name and Query String for Content Disposition will be ignored.
If Content Disposition by URL and Content Disposition by HTTP Header Match are both enabled, then by default, Content Disposition by URL will override Content Disposition by HTTP Header.
When configured, Content Disposition by URL overrides Content Disposition by HTTP Header Match.
Custom Mime Types
You can use the Custom Mime Types (Delivery) feature to configure how the CDN interprets file extensions into mime types for web browsers that rely on mime type extensions to define display behavior.
This feature is useful when your origin is unable to deliver a MIME type.
MIME type is used to identify the format of a file so that a browser can open the file with the proper extension or plugin.
MIME stands for Multipurpose Internet Mail Extension.
Specifically, you can use the following feature:
- Using Custom Mime Types allows to map file extensions directly to mime types. For example, you can tell the CDN that if the CDN sees the “.jpg” extension, then the CDN should automatically map that extension to the “image/jpg” mime type.
Edge Responses
You can use Edge Responses (Delivery) to configure response headers to deliver precise sets of information to end-users.
Specifically, you can use the following feature:
- Use Cache Rule to trigger specific status codes for specific URLs or domains. Specifically, you can use:
- Response with Status Code to specify the status code that you want to be returned to end-users.
- Headers in Response to indicate the headers that should be included in the response to the end-users.
Media Delivery
You can use the Media Delivery (Delivery) feature to define how the CDN treats a variety of different media types, including flash media.
Specifically, you can use the following features:
- Use Flash Pseudo Streaming to define how the CDN delivers Flash media. Specifically, you can use:
- Initial Bytes Parameters to specify the initial bytes of a video that should be returned before sending the requested byte offset. Typically players use ib for this query string parameter.
- Frame Start Offset Parameter to specify the specific byte offset into the requested video. Typically, players use fs for this query string parameter.
- Use Pseudo Streaming to enable Flash-based video players to support seeking to random locations within an MP4 or FLV file without having to download the entire video. Flash players, such as Flowplayer and JWPlayer, can be configured to send a query string parameter that indicates to the server the time offset the user advanced the video to. Typically a query string parameter named start is used by these players. Specifically, you can use:
- Jump-To-Time Start Parameter to indicate to the CDN the specific time interval of the video that is being requested.
- Jump-To-Time End Parameter indicates to the CDN the end time of the video that should be returned.
- Use Reserved Query String Parameters to define special customer query string parameters the CDN will use to alter responses. Specifically, you can use:
- Content-Disposition File Name Query String Parameter to specify the filename used in the Content-Disposition header.
- Content-Disposition Header Override to override the whole value in the Content-Disposition header.
- Content-Disposition Type to specify the type (inline or attachment) used in the Content-Disposition header.
Delivery Behaviors
You can use the Delivery Behaviors (Delivery) feature to control how content is delivered to end-users with headers and forced downloads. You can configure how content is delivered to your users.
Specifically, you can use the following features:
- Use Custom HTTP Response Headers to enable and bypass certain origin headers that affect the delivery of content. Specifically, you can use:
- Transfer Origin ETag Header to transfer the Origin Etag header by default. The Origin ETag header is more specific than a modified date. Since you can have 2 versions of the same file that were created at the same time, the ETag is a way of coordinating freshness with your origin that may differ from the last-modified header.
- Force Download by User-Agent to bypass the Origin’s Content-Disposition header and force download files to the user's hard drive.
Error Redirects
You can use Error Redirects (Delivery) to redirect users who encounter status code errors to custom response URLs. Specifically, you can use the following features:
- Use Exceptions to Response Code Redirection to specify which web browsers or user agents should not see the custom response URLs based on redirect code.
- Use Response Code Redirection to redirect users to the custom response URL, based on the error response code they encounter.
Request and Response Headers
You can use the Request and Response Headers (Delivery) feature to insert custom HTTP headers into requests and responses to and from the CDN.
Specifically, you can use the following feature:
- Use Static Header Injection to insert HTTP headers into the CDN request and response process. Specifically, you can use:
- Headers for Requests Made to the Origin to insert these headers into requests made to the Origin.
- Headers for Client Requests to the CDN to insert these headers into client requests made to the CDN.
- Headers for Responses from the CDN to insert these headers into responses from the CDN.
Custom Domains
You can use Custom Domains (Delivery) to instruct the CDN to interpret file extensions into MIME types for web browsers that rely on MIME type extensions to define display behavior. Custom MIME types are useful if your origin is unable to explicitly set the MIME Type.
MIME Type is used to identify the format of a file so that a browser can render or open the file correctly. MIME stands for Multipurpose Internet Mail Extension.
The Custom MIMETypes setting allows you to map file extensions directly to MIME types. For example, you can tell the CDN if it sees the “.jpg” extension, to automatically map that extension to the “image/jpg” MIME type.