Feature Focus: API/CLI User Token Management

CAST Highlight’s API is now used extensively across our user base for various scenarios such as building custom reports or integrating our insights into third-party products (e.g., MEGA, Alphabet, Azure DevOps, and Atlassian JIRA to name a few). Hence, there was a need for a more secure and flexible way to manage user access. This article describes how to create, manage, and use OAuth2 tokens to work with the CAST Highlight API or the command line interface (CLI).

What is OAuth2?

OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, etc. The OAuth 2.0 authorization framework is a protocol that allows a user to grant a third-party web site or application access to the user’s protected resources, without necessarily revealing their long-term credentials or even their identity.

CAST Highlight users can now authenticate to use the API (or CLI) by providing them with an anonymous token that is sealed by the company tenant identifier and a secret pass phrase that only the user knows and defines.

This article describes how to manage and use these tokens in CAST Highlight.

How to enable, create and revoke user tokens

The User Token Management feature can be activated at the portfolio level. As a Portfolio Manager being active at the root-level of the portfolio, navigate in the CAST Highlight portal to COMPANIES > Token Management:

  • Switch “on” the feature for the entire portfolio
  • Define a secret pass phrase
  • Define the duration (in minutes) of the policy for user tokens that have been created within your portfolio
  • Click “Apply”

This feature must be activated for each client by CAST. Therefore, if the portal does not allow you to activate the token authentication mode, please contact the support team or your preferred CAST consultant.

Once the feature is active, every user from your portfolio can create a personal token. To do so, from the User menu on the right, click on “Generate Access Token”. The next section describes how it is used.

As a Portfolio Manager, you can view other users’ token information on the Token Management page in case they ever need to be revoked. To revoke a token (i.e. the token will be disabled for using the API and/or the CLI), click on the trash icon.

How to use tokens with the API and the CLI

Here is how to use a token with CAST Highlight’s API and CLI:

  • API user authentication: Switch to the token authentication mode by replacing “Basic {base64(login:password)}” with “Bearer {your_token}” as shown below. Other than this change, the API will work exactly as before


  • CLI user authentication: User authentication is only needed when you want to automatically upload scan results of an application to the CAST Highlight portal. In this case, replace either the –login –password pair or the –basicAuth option with the new –tokenAuth as shown in the example below. The rest of the upload options (–companyId, –serverUrl, –applicationId) remain unchanged

java -jar HighlightAutomation.jar --sourceDir "c:\temp\src" --workingDir "c:\temp\hlresults" --companyId {companyId} --serverUrl https://rpa.casthighlight.com --applicationId 12345 --tokenAuth {your_token}

How to create/renew tokens from the API

User tokens can be create or renewed programmatically from the API by using the following endpoint and Basic or Bearer authentication:

GET {serverUrl}/auth/oauth/authorize