Summary: an explanation of how to authenticate with the RestAPI using an API key - primarily to enable the Report Generator to authenticate when SAML mode is active.


If you have enabled SAML authentication mode for your CAST Dashboard/RestAPI deployment, certain CAST features and services will not be able to authenticate to access data, for example:

This is because SAML is designed as a single sign-on mode for browsers and therefore non-browser clients (like Report Generator and CURL) cannot use the protocol. In order to resolve this issue, CAST provides the ability to define an API Key in the CAST dashboards/RestAPI that can be used to bypass SAML authentication.

  • An API Key is available in CAST Dashboard package v. ≥ 1.11.0.
  • It may also be necessary to do this when using LDAP authentication mode.

How does this work?

  • SAML authentication mode is enabled and configured for your CAST dashboard/RestAPI deployment
  • In addition, an API Key is defined in the file (WAR 1.x) or file (WAR / ZIP / JAR ≥ 2.x) in your CAST dashboard/RestAPI deployment
  • The API Key is used instead of a password in clients that cannot authenticate using SAML
  • Clients must use two specific HTTP headers to ensure that the API Key is used (Report Generator is pre-configured to send these headers)
    • X-API-KEY: the API Key matching the key defined in the or file
    • X-API-USER: a defined user name to obtain a CAST dashboard/RestAPI role and data authorization
  • When an API Key is used to bypass SAML mode, the user will be automatically granted the "ADMIN" role even if this role has not explicitly been granted to the user in question.


Configuring an API Key is simple. Locate the following file in your CAST dashboard/RestAPI/integrated RestAPI deployment and edit it with a text editor:

WAR 1.x

WAR ≥ 2.x

ZIP ≥ 2.x

JAR ≥ 2.5

Locate the following section:


First uncomment the security.apikey line:


Now add a key after the = sign on the security.apikey line. You can use any string of characters - CAST recommends generating a random string of at least 16 characters, for example:


Following any changes you make, save the / file and then restart your application server so that the changes are taken into account.

Using the API key

Report Generator

To use the API key, you can define it in the GUI or via the command line (both the traditional Windows version and the cross-platform CAST Report Generator for Dashboards version). See the following documentation for more information:



Automated actions using CURL

To use the API Key in automated CURL actions, use the following syntax:

  • X-API-KEY: the API Key matching the key defined in the / file
  • X-API-USER: a defined user name to obtain a CAST dashboard/RestAPI role and data authorization

An example is given for reloading the server cache.