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.

Managing Common REST API session tokens and user tokens

The Common REST API uses user tokens and session tokens to manage your API usage:

  • When you login, you are issued a user token that identifies you as a valid user of the API. 
  • Each time you access a service, you are issued a session token.

Both types of tokens expire if not used for the length of time set by the timeout value. By default, the timeout value is 15 minutes.

Depending on your system resources, the number of sessions that you can have open simultaneously might be limited. BMC recommends that you reuse the associated session token for multiple getData queries from the same view.
Because all data for the view is cached upon a getData request, reusing the session can result in better performance and optimum resource usage.
If you do not plan to reuse a session token, use the close API command to close the session directly. This immediately frees any resources associated with that session.

(Optional) Modifying the timeout value

If you want to modify the timeout value for session tokens and user tokens, use the following procedure:

  1. Navigate to your /tomcat/conf folder.
  2. Open the timeout.json file.
  3. Set the timeoutValue parameter to the number of minutes that you prefer.
    The minimum value is 5 minutes. Values that are smaller than 5 minutes automatically default to 5 minutes.
    The maximum value is 1440 minutes (24 hours), Values that are greater than 1440 automatically default to 1440.

Best Practice

When you are done with a session, it is best to issue a close command directly to prevent too many sessions from being open at one time.

You can also modify the timeout value. If you do not expect to reuse any sessions, reduce the timeout value so that sessions time out faster when not closed directly.
If you intend to reuse sessions, you can set the timeout value to a higher value so that you have a longer time period to reuse the session. In this case, it is important to close unneeded sessions directly when you don't need them anymore, because it will take them longer to timeout.

Reusing a session token

To reuse a data session, append the the following parameter to the getData request.


Closing a session

If you no longer need a session that is open, you can use the following syntax to close it:


Using the keepAlive command

If you want to keep a session alive for future reuse, issue a keepAlive command. You can issue keepAlive for either a user token or a specific session. The session parameter is optional. In either case, the user token is kept alive as long as any associated sessions are alive.




  • In Authorization, set Username and Password to your Tomcat user credentials.
  • In the Body, set the following key: 
    <userToken> is the token issued to you when you logged on. For more information, see Logging in to a service using the Common REST API.

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