API tokens

Security > API tokens

Use the API tokens screen to generate and monitor API tokens used to enable communication between NAM components, and to enable third-party software to access NAM monitoring data via our REST-based API.

Internal API token

The internal API token is required to authenticate communication between separately installed NAM components. There is only one NAM token per installation, but you can regenerate it (replace the current one with a new one) if needed for security reasons.

Click the token name (NAM) to display the current token value and editing options:

  • Regenerate - generates a new token value

  • Copy - copies the value to the clipboard

  • Cancel - closes the editing options without saving a new value

  • Save - saves the new (regenerated) token value and closes the editing options

    Internal API token - use case

    When you are installing a NAM Server, the NAM Console Connection screen in the NAM Server installer asks you to paste an API token into the installer, or to provide system administrator credentials and then automatically generate a token.

    You can generate a token automatically or paste a token into the installer.

    To generate a token automatically

    1. Select Get token automatically in the installer.
    2. Enter your NAM system administrator credentials.
    3. Click Next to generate the token and proceed with NAM Server installation.

    To paste a token into the installer

    1. In the NAM Console navigation menu, open Security > API tokens.
    2. In the Internal API token section, select the API token and click Copy to copy the token to the clipboard.
    3. In the NAM Server installer, on the NAM Console Connection screen, select Enter token and paste the token into the API token box.
      • You can of course paste this token into an interim application (such as a text editor or mail application) to transfer the text file to another machine. The security level of such a transfer is your responsibility.
    4. Click Next to proceed with NAM Server installation.

Changing Internal API token on NAM Server

When you regenerate the internal API token on the NAM Console, you'll need to change it on the NAM Server, otherwise they won't be able to connect to NAM Console.

If you use a farm, change the internal API token on the primary server only:

  1. In Windows, open the Apps & features control panel.

  2. Click the NAM Server in the list of installed programs and select Uninstall.

    You will not actually uninstall the software here. We just need to start the installer that originally installed the software.

  3. When the Welcome screen opens, select Change options and click Next.

  4. The server must be stopped before you can reconfigure it. When you receive a warning, read it and click Next.
    It may take a few moments to stop the software.

  5. Paste the new token or get one automatically using your administrator credentials exactly as you did during the installation.

  6. Click Next, review the summary, and then click Finish to commit your change.
    Be sure to indicate whether to start the NAM Server after the reconfiguration.

Public API tokens

A public API token is used to authenticate access to NAM monitoring data via our REST-based API. (When your app sends a REST request, you include a public API token in a header to authenticate the request.)

See DMI service method reference for details.

To obtain a public API token:

  1. In the NAM Console navigation menu, open Security > API tokens.
  2. If no public tokens are listed in the Public API tokens section, generate a token.
    1. Click Generate token.
    2. Provide a useful name for the token.
      For example, the name of the person, department, or company to whom you will distribute the token.
    3. Click Save.
  3. Select the API token you need.
  4. When the edit buttons are displayed for that token, click Copy to copy that token to the clipboard.
  5. Paste the token into the application that will use it to authenticate communication with NAM.
    (Or paste the token into a text editor so you can save and distribute the token.)
    In general practice, you will provide it to the application you use to access NAM data, and that application will pass it to NAM in a REST request.

Public API tokens - example

In this example, we use the Postman REST client (one of many such third-party clients available to download) to issue a getApplications request to retrieve a list of applications from a NAM Server. In real life, you would add such functionality to your own app, so it can use our REST API to get information from a NAM Server.

  1. In the NAM Console navigation menu, select Security > API tokens.

  2. Create or select a public API token and copy the token to the clipboard. You will need this value later.

  3. In Postman, create a request of the form http://ipaddress:port/rest/dmiquery/getApplications.

  4. Set Authorization to No Auth. We take care of authorization in the next step.

  5. On the Headers tab, we want to create an Authorization header containing the token as a Bearer value.

    • Enter a Key called Authorization
    • Enter a Value of Bearer followed by a space and then the full public API token.
  6. Click Send to send that request to the specified NAM Server.

  7. If the call is successful, you will get a response from the NAM Server such as:

     "offset": 0,
     "resultsCount": 8,
     "count": 8,
     "results": [
             "NAM Server"
             "Transaction Trace View"
             "Layer 2"
             "NAM Probe Statistics"
             "Enterprise Synthetic Health"
             "Advanced diagnostics on demand"