Space banner


This space provides the same content as before, but the organization of the home page has changed. The content is now organized based on logical branches instead of legacy book titles. We hope that the new structure will help you quickly find the content that you need.

Logging in to a service using the Common REST API

This topic was edited by a BMC Contributor and has not been approved.  More information.

To retrieve data using the Common REST API, you must log in to the service from which you want to retrieve data. 

Before you begin

Optionally, you can use the following procedure to obtain a list of services that are registered to work with the API. If you already know the name of the service to which you want to log in, you can skip this procedure.

  1. Go to https://hostName:portNumber/cra/ServiceGateway/Services
  2. Set the Authorization  header type to  Basic Auth
  3. Set Username  and  Password  to your mainframe user credentials for accessing Tomcat. 
    You must have the following SAF permission defined: 
    <role rolename="BMCCRA-rest" safclass="EJBROLE" safentity="TCAT.DEV.MANAGER" saflevel="READ"/>


    The user name reflected in the header might not be the user who logs in to the MainView service. For more information, see To log in to a MainView service.

    In curl, the URL would resemble this example: 
    curl  -u username:password  http://localhost:8080/cra/ServiceGateway/Services/

The  Services  request returns a JSON file listing the registered services. In the following example, the ellipsis at the end indicates that the returned JSON might include additional entries of this structure:

Services JSON
        "HOSTIP": "",
        "STATUS": "ACTIVE",
        "PORT": "22101",
        "WEBSERVICEName": "MVERESTAPI_SYSX_22101",
        "TLS": "N",
        "TYPE": "MV",
        "HOSTCN": "SYSX"
        "HOSTIP": "",
        "STATUS": "ACTIVE",
        "PORT": "4411",
        "TLS": "Y",
        "TYPE": "MV",
        "HOSTCN": "SYSX"

To log in to a MainView service

Use the following URL for logging in to a service using the API:


In the above example:

  • <hostname> is the name of the mainframe host where the Tomcat server is running.
  • <portnumber> is the port number of the Tomcat server.
  • <servicename> is the name of the registered service. For example, in the example JSON code shown above, the name of the first registered service is MVERESTAPI_SYSX_22101.
  1. Set up an HTTP request:
    • In the Header, set the Content-Type to application/x-www-form-urlencoded

    • Set the Authorization header type to Basic Auth. Set Username and Password to your mainframe user credentials for accessing Tomcat. This user must have the required SAF permission defined.
    • In the Body, set the following keys:

        • username=<username>

        • password=<password>

      <username> and <password> in the Body section are your credentials for logging into the MainView service. This user must have permission to access the data. This user does not require the SAF permission that is required for accessing Tomcat (unless it is the same user).

  1. Issue the Logon request.
    The API returns a 32-character user token: 

    Example of a User Token
    	"userToken": "38651614-99ca-4ec8-90ce-334475abc0f4"

    Until you log out or the token expires. you must pass this token in all subsequent requests from the selected service. For more information, see Retrieving MainView data using the Common REST API.


If you do not log out, the user token expires after the period of inactivity that the timeout value defines.  The default timeout value is 15 minutes. For more information, see Managing Common REST API session tokens and user tokens.

Was this page helpful? Yes No Submitting... Thank you