JWT Authentication and the Refreshed SDK Overview

Momentus is simultaneously launching two new major improvements for the Momentus Enterprise API: the addition of JWT authentication and a rewrite for the SDK.

What is a JWT? 

A Javascript Web Token (JWT) is a way to pass information securely around the web. It is often used to craft tokens used for authentication, as is the case here. For additional information, see the JWT introduction site.

Where does the API come in, and how is it different from the previous token?

The API, up until now, solely used Momentus Enterprise Authentication to get a token for performing calls. This means sending in your User and Password to receive back a token to use in your API calls. Now, you generate your own JWT and send it in, bypassing the initialization step.

Why make this change?

There are numerous benefits for you built into the new changes. See below for a highlight of just a few of those benefits: 

No More Initialization Call

To understand the fundamental flow change, it's important to understand how previous API calls flowed to the software:

The first step in that flow is an access request. 

With JWT, API calls to the software are more like this:

The software now skips the authorization step that returns the token. This is because, before the first call, your client app itself generates a token to include. Through the fundamentals of JWT, the software can know the call with your generated JWT is trusted.

Better Security Standards

Momentus Authorization requires the initial token to have a user and password sent in. This user is also shared with back office access.

JWT Authorization uses API users dedicated for API use only. Also, the secret used to authorize is never sent over any network. JWT is a widely accepted industry standard for this reason.

Performance

Not only can you save time not retrieving a token from the software, but calling the API is much faster now with dedicated authentication and authorization designed purely for API calls.

More API User Security Control

With API users, you can restrict what API endpoints the API user can access. You can also do a less disruptive security refresh with API Users compared to resetting a password.

Proxied Users 

A long requested feature is Proxied Users. This option allows the API user to mask itself as any user to perform lookups and saves. Doing this shows the proxied user as the one who performed updates.

Choice Over Token Life

You generate your token, and you also choose how long the token lasts. When using the SDK, you can even tell it to manage it's own token life and regeneration.

New In-Memory SDK

The new SDK focuses on an in-memory client that lives and manages itself with your application. It is filled with improvements and quality of life upgrades. See The Refreshed SDK section for more.

No Total API User Number Restrictions

Unlike software users, you are not restricted in creating API users. it is recommended to create one API user per calling application, resulting in a much cleaner application authorization set up.

Do I need to change now?

You do not have to update today but it is recommended to upgrade to the new JWT authentication and/or the new SDK when doing any new API development. Momentus plans for the two authentication types to co-exist for the immediate future but since security and features are far better for JWT, Momentus Enterprise Authentication ability for the API is planned to be phased out in the future.

What are API users?

Prior to this upgrade, any API calls were done using Momentus Enterprise Authorization users. We have added a new type of user dedicated for API use, called API Users. See API Users for additional information.

The Refreshed SDK

With a new authentication method, it was necessary to implement this in the SDK. We took the opportunity to make many upgrades to the SDK at the same time, creating the biggest launch in the API's history.

Name Change

If you are an API SDK user from version .96 or prior, note that the package names and versioning changed.

The name is updated to follow a more standard namespace convention. It is also more descriptive on what the package contains, namely models or the SDK that uses those models. 

Versioning

We have also removed the "One package per Enterprise version" style. There is now a single package uploaded to NuGet for all Enterprise versions, and the package version is what denotes the Enterprise version. Having one name allows you to have far more seamless upgrades of the package, as well as easier maintenance and locating of the package. The second value in the package version matches your Enterprise version, so if you are on version .98, you can download the latest 1.98.XX.XX version. 

Minimum Requirements

The new SDK is upgraded to .NET standard 2.0. Along with using .NET, ensure your version is compatible with Standard 2.0.

Call the API Using the SDK

This is the easiest way to implement the new JWT system and is highly recommended if you have the choice. 

Once you upgrade to the new SDK package on NuGet, you have all the necessary libraries. You just need to set up the call. The fastest way to get started in .NET code is to download our GitHub example project for your respective software version. 

See below for sample code: 

var auth = GetApiClientAuth();
var client = new Ungerboeck.Api.Sdk.ApiClient(auth);

private static void GetApiClientInfoAuth()
{
  return new Ungerboeck.Api.Models.Authorization.Jwt()
  {
    APIUserID = “MYUSERID”
    Key = “GET-THIS-GUID-FROM-API-USERS-WINDOW”
    Secret = “GET-THIS-GUID-FROM-API-USERS-WINDOW”
    ProxiedUserID = ”OPTIONALID”,
    UngerboeckURI =“http://mydomain.ungerboeck.com/test“,
    Expiration = System.DateTime.Now.AddMinutes(1) //Instead of a static DateTime, you can set the AutoRefresh ability (see below)
   };
}

We recommend setting the expiration to the normal call length with the addition of some extra time for network congestion. You can directly set the Expiration and manually update it yourself as needed, or you can use the AutoRefresh ability. This checks if the expiration is nearing and automatically refreshes the JWT before the call. 

      var autoRefresh = new Authorization.AutoRefresh
      {
        ExpirationInMinutes = 1,
        MinimumTimeBeforeRefreshInSeconds = 30
      };

      var auth = new Authorization.Jwt()
      {
        APIUserID = "NIGHTLYRUN",
        Key = "9ac7x632-2724-4098-82b9-38bb89c7247e",
        Secret = "484ff4ea-1b2c-4ecf-8645-44ba776d6b89",
        AutoRefresh = autoRefresh,
        UngerboeckURI = "https://my.ungerboeck.com"
        //Note: not setting expiration
      };

For making specific calls, the API client is upgraded to live as an in memory client object. 

A GET account command as: 

var account = apiClient.Endpoints.Accounts.Get(orgCode, accountCode); 

Call the API Without the SDK

While the SDK is the easiest way to get started with the API, it is dependent on the .NET platform. If this is not possible, you can still call the API through any HTTP library.

The JWT and Its Claims 

Here are the claims needed when generating your JWT:

Header

This includes standard signing information for the JWT. alg denotes the signing algorithm, which is HMAC SHA256, shortened to HS256. typ refers to the token type, which is JWT.

{  
  "alg": "HS256", 
  "typ": "JWT" 
} 

Payload

This contains the collection of claims that identifies the API user and token options

• iss – API User ID. Collect this from the API Users screen in the software.
• exp - Expiration time in Unix epoch time. You can set this to any length, but we recommend making this reasonably short.
• iat - Issued at in Unix epoch time. Typically set to now.
• nbf – Not before in Unix epoch time. Typically set to now.
• key [custom claim] - Any of the API User Keys assigned on the API user. This is a GUID from the Key section on the API User screen.
• sub - Optional. The User ID of the user for the application requesting delegated access. Must have permission. If left out, the API Client itself is the active user.

{ 

  "iss": "APIUSERID" 

  "exp": 1641501119

  "iat": 1641491688  

  "nbf": 1641491688

  "key": "7c8cafd6-9997-4988-a48f-dbdac82f316a"

  "sub": "RUDYS"

} 

Signature

This section includes a base64 encoded header and payload, then uses the API User's secret (found on the API User screen in the software) to sign the string with the HMACSHA256 algorithm.

{ 
    HMACSHA256(
      base64UrlEncode(header) + "." +
      base64UrlEncode(payload),
      secret) 
}  

When you combine all of this, you have a JWT that looks like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJBUElVTklUSldUIiwiZXhwIjoxNjQxNTg3NTEyLCJpYXQiOjE2NDE0OTE2ODgsIm5iZiI6MTY0MTQ5MTY4OCwia2V5IjoiODQxNGZmOTQtOTYwNS00MGVjLTk0OTEtNGZlOWU1NDNiMzE5Iiwic3ViIjoiQVBJVU5JVCJ9.nF1t72b90zv_rEBa5CZGD0o3CQAXldmoc-mk7FXzPVo

With your generated JWT, you can add it as a bearer token on an https call to the API.

Note: If you are writing this by hand as a trial, we recommend testing with the app on jwt.io. 

Once you have a valid JWT, to to the API Help page and click the Add Authorization button. The Add API Authorization screen opens.

Select JWT. Enter the JWT string into the JWT field. Click the Test JWT button. 

A message displays with the success or failure for the test call.

Javascript (Example Project) 

Using .NET to make UPI apps is highly recommended, but if you need Javascript, click here for a Javascript example. 

Tip: Use jwt.io to ensure your JWT and your secret validates properly if you are having issues authorizing. 

Other Languages 

Postman is a good way to see an example HTTP call that you can run with little set up.

Click here for a Postman example. This example contains a prescript that manually puts together the JWT.

If you import it into your local setup, you can use it to make calls using Postman. 

We recommendd libraries found on jwt.io for other languages.