MLink API Keys

MLink API Keys are used to authenticate with the MLink API, typically for machine-to-machine applications. This page documents how developers can obtain and use API Keys to connect to MLink servers.

MLink API Keys are encrypted on the backend, and SpiderRock does not retain a copy of the unencrypted API Key. When a key is created, the unencrypted key is returned to the user and should be stored securely. If the key is lost, it must be deleted and a new key must be created.

Obtaining an API Key

You can obtain an API Key either through the home page or through the MLink API. In order to create, modify, or delete API Keys, your UserConfig must have hasApiKeyAccess set to Yes.

The simplest way to obtain an API Key is through the SpiderRock Connect home page. On this site, you can create a new API Key by clicking the "Create API Key" button and following the instructions.

Using an API Key

You can provide the API key in the Authorization header of your HTTP requests. The header should be in the following format:

Authorization: Bearer $MLINK_API_KEY

Alternatively, you can pass it in the URL as a query parameter:

https://mlink-live.nms.venus.spiderrockconnect.com/rest/json?cmd=...&apiKey=$MLINK_API_KEY

API Key Management via the MLink API

Managing API Keys through the MLink API is primarily useful for lifecycle management of these credentials.

You will need a valid API Key or Session Key to authenticate your request. If you do not already have an API Key, you can obtain a Session Key with your username, password, and MFA credentials.

Inserting (Creating) a new API Key

1. To create an API Key, use cmd=postmsgs with a message type of UserApiKey and a message body that includes the following fields:

• label: A user-defined label for the API Key
• expire: The expiration date for the API Key
• action: Insert to create a new API Key

Example URL for posting:

curl -vv --request POST 'https://mlink-live.nms.venus.spiderrockconnect.com/rest/json?cmd=postmsgs' \
     -H "Authorization: Bearer $MLINK_API_KEY" \
     --data-raw '{
       "header": {
         "mTyp": "UserApiKey"
       },
       "message": {
         "id": null,
         "expires": "2024-12-31 00:00:00.000000",
         "label": "my first api key",
         "action": "Insert"
       }
     }'

You can substitute a Session Key for the API Key if you prefer.

2. The MLink server will respond with a message that includes the new API Key:

Example response:

{
  "header": {
    "mTyp": "UserApiKey"
  },
  "message": {
    "id": 1,
    "expires": "2024-12-31 00:00:00.000000",
    "created": "2024-09-27 21:30:02.951423",
    "label": "my first api key",
    "plaintextApiKey": "C0FFEE00-3141-5926-5358-979323846264",
    "success": "Yes",
    "action": "Insert"
  }
}

plaintextApiKey is the unencrypted API Key that you should store securely.

Updating an API Key

To update an API Key, use cmd=postmsgs with a message type of UserApiKey and a message body that includes the following fields:

• id: The ID of the API Key to update
• label: A user-defined label for the API Key
• expire: The expiration date for the API Key
• action: Update to update an existing API Key

You may only update the expire and label fields of an API Key.

Example:

curl --request POST 'https://mlink-live.nms.venus.spiderrockconnect.com/rest/json?cmd=postmsgs' \
     -H "Authorization: Bearer $MLINK_API_KEY" \
     --data-raw '{
       "header": {
         "mTyp": "UserApiKey"
       },
       "message": {
         "id": 1,
         "expires": "2025-12-31 00:00:00.000000",
         "label": "my updated api key",
         "action": "Update"
       }
     }'

Deleting an API Key

To delete an API Key, use cmd=postmsgs with a message type of UserApiKey and a message body that includes the following fields:

• id: The ID of the API Key to delete
• action: Delete to delete an existing API Key

Example:

curl -vv --request POST 'https://mlink-live.nms.venus.spiderrockconnect.com/rest/json?cmd=postmsgs' \
        -H "Authorization: Bearer $MLINK_API_KEY" \
        --data-raw '
        {
          "header": {
            "mTyp": "UserApiKey"
          },
          "message": {
            "id": 1,
            "action": "Delete"
          }
        }'

Listing API Keys

Example:

curl -vv POST 'https://mlink-live.nms.venus.spiderrockconnect.com/auth?cmd=getusermetadata' \
     -H "Authorization: Bearer $MLINK_API_KEY" \
     | jq '.[0].message.ApiKeys'

Example response:

[
  {
    "id": 1,
    "label": "my first api key",
    "expires": "2024-12-31 00:00:00.000000",
    "created": "2024-09-27 22:04:11.664419"
  },
]

Note:

The plaintext API Key is not returned in the list of API Keys. It is only available when you create the API Key.