IBM API Hub
Maximo Application Suite Admin APIs 9.0.x

By IBM Maximo

Provides REST APIs for performing Suite administration operations.


API URL


The Maximo Application Suite REST APIs are all accessed via a URL which has the following format:

api.<mas-instance-id>.<mas-domain>

Where:

  • mas-instance-id is the name associated with your Suite installation
  • mas-domain is the domain of your Suite

For example, if you access your Suite Administration UI via https://admin.prod1.acmeco.prod.com, then:

  • your mas-instance-id would be: prod1
  • your mas-domain would be: acmeco.prod.com

And you would use the following URL as the basis for interacting with the REST APIs: api.prod1.acmeco.prod.com

Authentication


Almost all of the REST APIs for performing Suite administration operations use token based authentication. The token is provided via the x-access-token header of each request:

GET /v3/users/user123
x-access-token: eyJraWQiOiJlMFg3T0pvS1VqYmthQnVVX3JxRFBaUGdKVlRrbWZWT...

The exception to this is the v1/authenticate endpoint, which uses HTTP Basic Authentication.

Obtaining an authentication token


To obtain a token for authenticating REST API interactions you must use API Key credentials to issue a GET request with HTTP Basic Auth to the /v1/authentication API endpoint. This will issue a time limited token in the response which can then be used in the x-access-token header when interacting the the other APIs.

The credentials for the HTTP Basic Auth are the id and token of a Maximo Application Suite API key, which should be used as the username and password respectively (value of Authorization header is Basic <base64 encoded username:password>)

GET /v1/authenticate
Authorization: Basic YS1mZWR0ZXN0LWZkamFla3hrem9zczprZmhOVHJyNzNTR2xodWplOVdYSGFWOFFneTZMSjFsYlF4b21reHYtVEgwVmRKTUV2aEVHTUcyNWVmMC1HajZZcWpUYUtCSlg0TnRhZWo1Rjh4NUZydw==

<no request body required>

This will response with a JSON object containing a token field:

200 OK
Content-Type: application/json

{
  "token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJhLWZlZHRlc3QtdGNobmpnc2tzZWJrIiwidW5pcXVlU2VjdXJpdHlOYW1lIjoiYS1mZWR0ZXN0LXRjaG5qZ3Nrc2ViayIsImlzcyI6ImFwaS5mZWR0ZXN0LmFwcHMuZmVkdGVzdC5jcC5meXJlLmlibS5jb20vdjEvYXV0aGVudGljYXRlIiwiaWF0IjoxNjg3NDQ0NTg4LCJleHAiOjE2ODc0ODc3ODgsIm1hc3R5cGUiOiJhcGlrZXkifQ.pU1ySEqIVsdplBMZHIYHkLxKvQjuB1UAfW0goLRtiWRWCwsbdFCuF10I48dVKQn9hiuGzOVCE9U8dyJhAjURe8ko7ENMMdSxVDUohE6ZUjEohSX7wuwUJgtAxHpo_3M9A-bsjxOREnLQDv4Aixtzers4KsJxkAt5LQScY1qE_Wu7ihHm4nBLejMwU70_gBTA1Lp033QWmqg9sDBDJYs-3cUX5nyiAtg2XVJCxk4i3MXiUUKuHxTitvwRFQmR6FHluej-dEV8U553kzD8IvnKVq73hD0xorU5-FC7jF5LH9P_NMzcFD0RPXKPldFTBgmVB45dSrsCLWxff5gZyYys2mKJYMlF0U7_nVsrrhgvLQyT9XyNx3UO9z5aUc0YIA3NFGxotjFkz0IQ4fQPKzXVCgr1JCrjLKZpdHs3C5msrdD_aUwzocJi-4i7ZdFao4q-usvQCcD906dTJVWqTGUyBpYvh7bXnmQ90UKl-ZATzVw1ZgD315KTGGSTvfi09SE7iF_C_cnDRLaZL1yVXtx4rCzbt4qYuvcuJGe2_C3ZtrTFF0YmV48ULxJs9ztdBVXb7LA0bAloTnLruz922_QwvqNxVnHLZ3aukkKmi81Rm32BTf-vSxrIxgukjyz6Pjkonfz-YS7QReYvgr7-_YNGoyxiEGBKsXcXfWYx9pfUl68"
}

The value of the token field should then be used in the x-access-token header of any other request to a Maximo Application Suite API.

Creating an API Key


In order to get an authentication token you first need a Maximo Application Suite API key.

API Keys can be administered via REST APIs or via the Maximo Application Suite UI:

  • In order to create an API Key via the UI, your user needs to have api key administration permissions (this can be assigned via another user or api key with that permission, or via the MAS Superuser)
  • In order to create an API Key via the REST API, you need to authenticate with a token for an existing API Key which has api key administration permissions

Using the "Try this API" feature


When viewing the specifications of the various REST APIs you will see that there is an option to "Try this API". Clicking on this will enable you to interactively issue a request against your Maximo Application Suite Instance.

In order for this to work you will need to enter a number of variables:

  • Server variables: This is where you enter the details of your MAS instance. See the API URL Section for more information
  • Security: This is where you enter authentication details. Set the Authentication Section for more information

You will also need to enable CORS (Cross Origin Resource Sharing) for the domain https://developer.ibm.com in your Maximo Application Suite configuration:

  1. You will need access to the Suite CR (Custom Resource) in the Openshift cluster where your Suite is deployed.
  2. You then need to update the spec.settings.cors.allowedOrigins to include the https://developer.ibm.com domain (see the example below).
  3. You will then need to wait for those updates to be reconciled. It may take several minutes before the changes take effect.

Example of update to Suite CR:

apiVersion: core.mas.ibm.com/v1
kind: Suite
metadata:  
  ...
spec:
  ...
  settings:
    ...
    cors:
      allowedOrigins:
        - https://developer.ibm.com
...

Open API Specification

About specification
API Version

9.0.6

Legend
Products & Services
Company information
Company logoIBM Maximo