API Users

To access the Momentus Enterprise API, you need to create a special type of user called an API User. Industry standards refer to these as service accounts. You can create and manage these users from the API Users screen in the software. While they share some of the same characteristics as a typical user account, API users are specifically designed to interface with API endpoints and feature unique authenticators to meet that purpose.

Add an API User

1. Click the API Users link from the Main Menu. The API Users screen opens.
2. Click the Add button. The Add API User screen opens.
3. Enter the necessary information:
   • Display Name - Name of the user to display in the software. For example, on entered and updated by user fields. Can include spaces.
   • ID - Value that identifies the user. Limited to 10 characters with no spaces or special characters. This value is required for API authorization.
   • Description - Additional information about the API user. This is much longer than the Display Name and can contain details and light notes.
   • Organization - Organization the API user belongs to. Users can only access and modify data within their own organization.
   • Allow Proxied Users - If checked, you can use proxied user IDs with the API user. 
   • Retire - If checked, the user is no longer active. You cannot use retired users.
4. Click OK. The following fields are populated when the user is saved: 
   • Secret - One of two generated values that is required for API authorization. You can regenerate and copy this value using the Tools button the top of the screen.
   • Keys Tab - A single entry displays in the tab. This is the second generated value that is required for API authorization. While there is only one Secret per user, you can have multiple Key values generated and used at the same time. You can generate new key values by clicking the Add button on the tab. To copy a key value to the clipboard, right-click on the key value and select Copy Key to Clipboard.

The ability to regenerate an API user's Secret and Keys gives you greater control over who can use the  API within your organization. If you need to restrict access, you can delete the corresponding key to lockout unwanted authorization.

You also need to review the following tabs for new API users:

• Allowed Endpoints - Determines which endpoints the API user has access to. If an API user attempts to access an API endpoint that is not allowed, an error is returned. If no allowed endpoints are selected, then all endpoints are allowed. To allow an API user access to an endpoint:
  1. Click the Manage button. The Add Allowed Endpoints to API User screen opens.
  2. Click the plus (+) sign to the left of the endpoint in the Available section to move a single endpoint to the Selected section. To move multiple endpoints to the Selected section:
     • Use Ctrl+Click or Shift+Click to select the endpoint(s) for the API user to access.
     • Click the single right arrow button to move the selected endpoint(s) to the Selected section on the right.
  3. Click OK.
• Access Privileges - You must also assign access privileges to the API user to allow access to certain actions and data. See Access Privileges for more information. To assign access privileges to an API user:
  1.  Click the Manage Access button. The Manage Access Privileges screen opens.
  2. Click the plus (+) sign to the left of the access privilege in the Available section to move a single access privilege to the Selected section. You can also move multiple access privileges to the Selected section but do not move all access privileges to the Selected section. This can have profound and unintended consequences for all your users. To move multiple access privileges to the Selected section: 
     • Use Ctrl+Click or Shift+Click to select the access privileges(s) for the API user.
     • Click the single right arrow button to move the selected access privilege(s) to the Selected section on the right.
  3. Click OK.
• Allowed Proxied Users - If you checked the Allow Proxied Users check box, you can use this tab to view and modify the proxied user IDs. You can use proxied users to mask actions performed by an API user and record them in the software as if they were performed by another user. The API user's secret and key is still used for authorization, but the changes in data are logged with the proxied user's ID. If no users are selected in the tab but the Allow Proxied Users check box is checked, then all valid user IDs are available for proxy. To manage proxied users:
  1. Click the Manage button. The Add Allowed Proxied Users to API User screen opens.
  2. Click the plus (+) sign to the left of the user n the Available section to move a single user to the Selected section. To move users to the Selected section:
     • Use Ctrl+Click or Shift+Click to select the user(s).
     • Click the single right arrow button to move the selected user(s) to the Selected section on the right.
  3. Click OK.

Best Practice Recommendations

One API User per App

We recommend using one API User per application that accesses the API. This makes sourcing data entry much easier. There are no limits on the number of API users you can have. 

Security Refreshes

For security refreshes, we recommend rarely refreshing the secret, as this is disruptive to apps running in production when suddenly the secret is no longer valid. Refreshing the Key is a better process for in production security refreshes. Below is an example scenario of how to refresh the key:

1. API User is in production and uses Key A to authenticate.
2. Whether a Key was lost or a general security refresh is desired, you want to generate a new Key. The administrator adds Key B. There are now two valid keys for the API User.
3. Key A is replaced by Key B for authentication in production.
4. Key A is deleted from the API user. There is now only one valid key.

Following this process results in minimal down time due to security refreshes.

Determining if a Proxied User Was Used

While proxied users almost fully mask the API user when performing adds and edits, there is a way to determine if the entry is saved by an API user. The Audit Log always shows if the API user is involved. See the below example:

Line 1 shows an account address modified by a proxied user via an API user.

Line 2 shows an account address modified by a typical user (i.e. a human using the software directly).

Line 3 shows an account address modified directly by an API user not using any proxied users.