MLink API Keys

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

MLink API Keys are encrypted on the backend and once SpiderRock does not have 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 created.

Obtaining an API Key

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

The simplest way to obtain an API Key is through the home page. On this site, you can create a new API Key by clicking on 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

Or 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

Example: API Key management using the MLink API

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

To obtain an API Key using the MLink API, you can use the following steps:

You will need a 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 you 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:

{
  "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 you 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 you 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 that the plaintext API Key is not returned in the list of API Keys, it is only available when you create the API key..