Skip to main content
Matrix42 Self-Service Help Center

Web Services tokens: Generate API Token

Web Services integration basics and authentication in the REST API services. Generating API token via user interface.

Overview

API Tokens is a special mechanism of Web Services authentication designed for 3rd party integration. Unlike other available authentication approaches in UUX,  the API Token mechanism does not require End-User interaction (to provide credentials for login), which allows for it to be used in background processes, e.g. for cross-process communications (example: Data Gateway communicates with Enterprise Service Management Services) or for interactions.

For more details about the Token Authentication see the Secure Token Service configuration

Security

The API Token is a widespread approach for implementing machine integration.  On creation of the API Token the System automatically generates the JWT token encoded with the Private Key using SHA256  algorithm. The Token is not persisted in the database, and is visible only to the person who requested it. Before closing the page with the Token, it must be copied for further usage.  

The Token (Secret) used by an integrated application must be properly protected to prevent unauthorized people from reading it. For example, Matrix42 Worker stores the API Token in the Config file encrypted with the Machine Key.

The API Token is regularly sent to the Application Server for verification of validity and issuing the short-time Access Token, which can be used to run Web API services.

If the API Token was not stored correctly and was compromised, the only thing you need to do to protect the System is to Delete or Disable the corresponding to Web Service Token in the Administration. 

For better security, it is recommended to issue API Tokens with a shorter lifetime (e.g. 30 days). 

Description  

To set up a connection with Web Services using the API token approach, a valid API token needs to be present in the System. In the Administration application, open the Integration → Web  Service Tokens area which presents all the Tokens. 

Run the action Generate New Token to issue a new API Token:

Generate API Token.png

  • Name: unique token name used to describe the purpose of the Token.
  • Expires at: specifies the number of days the token stays valid. Available options:
    • 30 days (default)
    • 90 days
    • 180 days
    • 1 year
    • Never Expires: keeps the generated token always valid until the moment the API Token is deactivated or deleted.
  • User: defines the Person associated with the Token. After successful authentication with API Token, the System uses defined Person permissions for authorizing access to System resources.

Once the API Token is generated, the System displays the Token on the action result page.

Copy API Token.png

The generated Token is not stored and is available ONLY right after the generation on the Action result page. Therefore, it needs to be copied and saved in a secure way somewhere for continuous use.

Example: Configure API Token for 3d Party integration

 Use Case: The 3rd Party application "ExternalApp" needs to be allowed to call a single Web Service method in Enterprise Service Management

  1. Create a Person in Enterprise Service Management, with name "ExtenalApp".
  2. Change the Audience of the needed Web Service Method to grant access to the "ExtenalApp" user
  3. Create API token for the "ExtenalApp" user
  4. Use the generated Token in external application 

Using API Token for Web Service call

The SolutionBuilder uses Access Token to authenticate each Service request. To obtain the Access Token the API Token has to be exchanged using a dedicated Web Service call:

POST /m42Services/api/ApiToken/GenerateAccessTokenFromApiToken/? HTTP/1.1
   Host: server.example.com
   Authorization: Bearer $ApiToken

The Access Token is issued for a short period of time, which allows mitigating risks when the API Token has been compromised.
For more information, see the how to Generate and Use API token article.

 

  • Was this article helpful?