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:
- You will need access to the
Suite
CR (Custom Resource) in the Openshift cluster where your Suite is deployed.
- You then need to update the
spec.settings.cors.allowedOrigins
to include the https://developer.ibm.com
domain (see the example below).
- 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
...