Docs Developer Site
Developer Docs Guillotine - Headless GraphQL API next Configuration options

Configuration options

Contents

The following configuration options are available for Guillotine

Config file

To configure Guillotine, add a configuration file to your XP instance’s config folder. This example enables CORS for two frontend origins without cookie credentials. Replace the origins with your frontend addresses, including the scheme and port when applicable.

com.enonic.app.guillotine.cfg
graphql.extensions.modifyUnknownField=throw

cors.origin=https://example.com, https://admin.example.com
cors.credentials=false
cors.allowedHeaders=Content-Type
cors.methods=POST, OPTIONS
cors.exposedHeaders=X-Request-Id, X-Custom-Header
cors.maxAge=3600

maxQueryTokens=15000
graphql.extensions.modifyUnknownField

Controls attempts to modify an unknown schema field: throw raises an error, ignore skips the modification, and warn logs a warning. Default is throw.

cors.origin

Allowed origins, comma-separated. Omit this property to disable CORS. Supports (all origins), literal origins, and ~-prefixed regular expressions for dynamic matching. ~. reflects any origin.

cors.credentials

Sets the Access-Control-Allow-Credentials header. Use true or false; the default is false. For cross-origin cookie authentication, set it to true, configure explicit allowed origins, and use credentials: 'include' in the browser’s fetch() request. Browsers do not accept the wildcard origin * with credentials.

cors.allowedHeaders

Sets the Access-Control-Allow-Headers header. If your client sends an Authorization header, include it, for example cors.allowedHeaders=Content-Type, Authorization. If this property is omitted, the request’s Access-Control-Request-Headers value is reflected when present.

cors.methods

Sets the Access-Control-Allow-Methods header. The Guillotine endpoint answers POST and OPTIONS requests only. The library default is GET, HEAD, POST; the example explicitly allows POST, OPTIONS.

cors.exposedHeaders

Extra response headers browser scripts may read beyond the CORS safelist. Listing a header does not create it; expose headers your deployment actually returns. Browsers treat * as a wildcard only for requests without credentials.

cors.maxAge

Sets the Access-Control-Max-Age header, specifying the preflight cache duration in seconds.

maxQueryTokens

Maximum number of raw query tokens. The parser throws an exception when this limit is exceeded. Default is 15000.

CORS controls which browser origins can read responses. Authentication and content permissions still determine which content the caller can access. See Troubleshooting when requests fail.

Image transformations

XP signs the image URLs it generates, so a query that can ask for any scale, quality, background, format or filter can have any image variant signed. A virtual host mapping decides whether the queries it serves may ask for them, with the guillotine.imageTransformations context property in com.enonic.xp.web.vhost.cfg:

mapping.mysite.host = www.example.com
mapping.mysite.source = /
mapping.mysite.target = /site/myproject/master/mysite
mapping.mysite.context.guillotine.imageTransformations = deny
auto

The default. Queries sent to Guillotine’s API endpoint, such as /api/com.enonic.app.guillotine:graphql, and in the admin may ask for image transformations; queries sent to Guillotine mounted on a site or a webapp may not.

allow

Queries may ask for image transformations.

deny

Queries may not ask for image transformations.

A query that may not ask for them gets a field error for each scale, quality, background, format or filter argument of imageUrl, and for the imageSrcWidth and imageWidths of processHtml. Without those arguments, imageUrl gives the image as stored, and rich text images keep the scale and style the editor chose.

Queries run in-process, through the guillotine.execute function, may always ask for image transformations.

Media base URL

When exposing XP’s shared API base URL, GraphQL, images and attachments are reachable under the same public base by default. Clients can use this base, or a separate CDN base, when building media links from path and queryString. Configure the public route to serve those paths. For a CDN host that serves the media API paths without their leading segments, see Serving media from a CDN host.

Guillotine returns media URL components without a base: paths such as /media:image/…​ and /media:attachment/…​, which your client prefixes with its media base.

Contents

Contents