Interfacing with REST apis using API keys

Apikeys are tokens that can be used to make rest api calls without needing to provide the user credentials. Apikeys are created for a given Maximo user and the api calls made using that apikey effectively works in the context of the said user. This implies all the user’s permissions are respected in that api call.
REST apis invoked using api keys use “silent” login. This implies that there is no MAXSESSION entries created. By default, there would not be any server-side web sessions. This implies that clients using rest apis with api keys, do not need to call the /logout api as there is no persistent server-side session. Api keys can be created and revoked as needed. There is only one api key per user allowed at this point. Each of these api keys may have an expiry (in minutes). The expiry time is specified at the time of creation. An expiry time of -1 implies the key will never expire. The only way to invalidate the key would be revoke it manually. Below we list the rest apis that can be used to create/revoke the api keys.

To create the api keys, login as the user for which you want to create the key and use the rest api shown below.

Body:

This will respond back with a json containing the apikey value. Note that you can use this same api again to regerate the apikey. This

To revoke that api key,

As you may have noticed, the create and revoke apis do not take in any user name as the user name is implicit from the logged in user.

In case, the adminitrator needs to do this for a given user, we can use the Object structure based apis using the MXAPIAPIKEY Object structure.

Body:

Note the userid maps to the MAXUSER.USERID attribute. The administrator can also get a list of the apikeys using

Administrator can also delete the api keys using the DELETE REST call

Note this Object structure was added only in 7611. For prior releases, customers can easily add a different object structure for this to do the same.

To make an api call using the api key, we need to add the apikey value as a query parameter or a request header to the rest api call. Note that it is recommended to use the apikey header (as opposed to the query parameter) for security reasons. Below is an example for fetching assets

While this model works out great for maximo authentication enabled deployments, it does not work out for app server authentication-based Maximo deployments. The reason being, in the latter model, the /oslc servlet is security constrained and hence the rest api calls would not be able to reach to the application code without the user credentials.

To overcome that, we have added a route /api in the maximouiweb modules web.xml which maps to the same oslc servlet. The mapping is shown below

We also need to make sure this mapping should not get protected using security-constraints. This way we can make sure the application server security would not interfere with the apikey way of authenticating the rest api calls. This /api mapping is not present in the maximouiweb modules web.xml file for 7609 or 7610 releases. If the need is to leverage the apikeys in app-server authentication enabled Maximo, we recommend adding this mapping to the maximouiweb modules web.xml.

With this mapping the rest api calls would look like:

Note that without the x-public-uri request header, the response json will have href urls pointing to the /oslc context and not to the /api context. Note that this call works for app server security, as the /api context is not protected using the security-constraints. The rest api framework makes sure that the rest api call does not go through unless the apikey is provided.

This model with apikeys (along with the /api route) provides a way to make headless client calls to the rest apis when Maximo is configured with interactive authentication schemes like SAML/OIDC which otherwise would need some browser-based interaction to authenticate.

Starting 7612, all apikeys will be encrypted at storage. This implies that anyone upgrading from a prior version will have their apikeys encrypted by the upgrade process. We introdced a maximo property mxe.apikeysysusers that can be leveraged to set comma separated list of user ids that we would want to block from creating apikeys by using the MXAPIAPIKEY Object structure. These users can however create their own apikeys using the /apitoken/create api.

There is also another maximo property mxe.apikeyforloggedinuser which when set to 1, will only allow the logged in user to create an apikey for that user only. This implies that with this property set to 1, the admin cannot create apikeys for other users. This setting is turned off by default.

Maximo apikey creation, supports externally generated apikey tokens. By default, the apikeys are Maximo generated unique ids. Maximo also allows this key to be generated externally. Maximo admin can turn off this support by setting the property mxe.allowexternalapikey to 0.