Manage Moogsoft Cloud API keys
Several commonly used Moogsoft Cloud features, including integration configurations and the API endpoints, require Moogsoft API keys. You can create and manage API keys under Settings > API Key Management.
API Key Management is used for storing API keys created in Moogsoft only. You can store API keys from external systems to use with Moogsoft in the Credential Store. See Store external system credentials for more information.
About API keys
Moogsoft does not include default API keys. You must create a key before you can use an API endpoint or integration requiring an API key.
API keys are viewable only when first created. You cannot view or edit them later.
It is a best practice to assign minimal permissions to an API key. Only include permissions that are necessary for the task you need to perform.
Each API key is associated with the user who created that key.
You can create multiple keys for yourself. It is a good practice to use a separate API key for each data stream if you want to set up multiple integrations.
The permissions you can assign to an API key cannot exceed your own role and permissions. See Custom roles permissions reference and Manage roles for more information.
API keys for integrations
Most integrations which require an API key do not require specific permissions and only require that the key is valid. If you need to create an API key to use with an integration, you can assign any permission to the key. We recommend assigning Read Only access for the Integrations permission to the key, since you must assign at least one permission.
The ServiceNow outbound integration is the exception, as it potentially requires an API key with Full Access to several features. See API key permissions for the outbound ServiceNow integration for details.
If you are creating an integration using an API endpoint, you must use an API key with Full Access permission for Integrations in the API POST request. The integration configuration only requires an API key with minimal permissions, as explained above.
Legacy API keys
Legacy API keys are those keys that were created before the ability to assign specific permissions to API keys was added to Moogsoft. These older API keys will continue to function as they have in the past. Legacy API keys have the same permissions as the user who created them.
If you are using legacy API keys that have excessive permissions for their function (such as keys created by Administrator users with Full Access to all features which are being used for integrations), you may prefer to create new keys with appropriate permissions, and then replace and revoke the old ones.
Create an API key
Add a new API key to use with Moogsoft features.
Navigate to Settings > API Key Management.
Click Add API Key at the top right of the page.
Use the fields provided to add a name (required) and a description (optional) for the new key.
Click +Add Permission and select the Moogsoft features that the key will allow access to.
Click Add.
In the Permissions list, choose whether the whether the selected permissions should provide Read Only or Full Access to the feature.
The default access level for each API key permission is Read Only. Any permission not selected will have No Access.
Click Add API key.
Copy your API key when it displays and save it in a secure text file. You cannot view the key again.
Revoke an API key
Revoke an API key if it is no longer needed, or for security reasons. The key will no longer work after it is revoked. To avoid any downtime or data loss, replace the key with a new key wherever it is in use before revoking the old key.
Navigate to Settings > API Key Management.
Click the key you want to revoke.
In the dialog box that opens, click Revoke This Key.
Confirm your selection by clicking Revoke again.
In about five minutes the key will be revoked and will no longer provide access.
Rotate API keys for deleted users
When a user is deleted, any API keys created by that user stay in the system. Retaining the old keys in this way makes it possible for your organization to create new keys with a valid user as replacement without losing access to integrations or scripts.
Removing an old key and replacing it with a new key is highly recommended, as an API key is a credential for accessing Moogsoft. Anyone with Full Access permission for User can perform the following key rotation procedure:
Create a new key in Moogsoft.
Apply the new key to the third-party tool or script, replacing the key associated with the deleted user.
Delete the old key.