Session service

The Session service allows you to log in and log out of Control-M and receive a token that can be reused in subsequent requests. In addition, the Session service allows users to change their own password.

session login

Log in to Control-M and return a session token that can later be used for subsequent requests using the -t option. 

A token is valid for 30 minutes.

Example for CLI:

> ctm session login
  "username": "emuser",
  "token": "E14A4F8E45406977B31A1B091E5E04237D81C91B47AA1CE0F3FFAE252AEFE63ADE182E5702F5A9131A2DA0A8E8AE76D7C3CCBA0B7",
  "version": "9.18.1"

>ctm config servers::get -t "E14A4F8E45406977B31A1B091E5E04237D81C91B47AA1CE0F3FFAE252AEFE63ADE182E5702F5A9131A2DA0A8E8AE76D7C3CCBA0B7"

Example using curl:


# Login
login=$(curl -H "Content-Type: application/json" -X POST -d "{\"username\":\"$user\",\"password\":\"$passwd\"}"   "$endpoint/session/login" )
echo $login
# trim spaces and new lines
login=$(echo ${login//[$'\t\r\n ']})
token=$(echo ${login##*token\" : \"} | cut -d '"' -f 1)
echo $token

session logout

Log out from the user session defined by the given token.

Using CLI:

ctm session logout <token>




The token obtained by the session login request

Example using curl:


curl -g -k -H "Authorization: Bearer $token" -X POST "$endpoint/session/logout"

session user:password::update

Enables a user to change his or her own password.

CLI Syntax

ctm session user:password::update [currentPassword] [newPassword] [-p]





The user's current password, either of the following:

  • Plain text
  • Predefined secret, with the following format: "Secret:<secretKey>"

A new password for the user, either of the following:

  • Plain text
  • Predefined secret, with the following format: "Secret:<secretKey>"

The password parameters are optional because you can, alternatively, use the -p (or -prompt) option through the CLI. With this option, you do not need to enter passwords in the command. Instead, after you enter the command, you are prompted for the current password and (twice) for the new password. Note that if you use both the password parameters and the -p option, the passwords that you enter through the command prompt override the passwords that you specify in the command.


See REST API reference.

When using a REST API command, you must provide your user name and passwords (or secrets) in a payload .json file. In the following curl example, note that the path to the payload file is prefixed with an @ character.

curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" 
-d "@data.json" -X POST "$endpoint/session/user/password/update"

Here is an example of the contents of a payload .json file, with the current password specified as text and the new password as a predefined secret:

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