Session Service

The Session service allows you to log in and log out of Control-M, receive a token to reuse in subsequent requests, and change a password.

The Session token is the only token type available in Control-M Automation API before version 9.0.21. BMC recommends that you create an API token with the Authentication Service, instead of a 30-minute Session token. API tokens are valid for much longer time periods than Session tokens, based on an expiration date that you define. You do not need Session tokens if you create an API token. For a further comparison of these two types of tokens, see Authentication Tokens.

The following API commands enable you to manage sessions:

session login

The session login command enables you to log in to Control-M and returns a session token for subsequent requests. A token is valid for 30 minutes.

CLI Syntax

The following shows the CLI syntax for the session login command:

ctm session login

Response

The following example shows the response.

Copy 
> ctm session login
{
"username": "emuser",
"token": "E14A4F8E45406977B31A1B091E5E04237D81C91B47AA1CE0F3FFAE252AEFE63ADE182E5702F5A9131A2DA0A8E8AE76D7C3CCBA0B7",
"version": "9.0.21"
}

You must type -t with the token for subsequent requests.

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

REST API Syntax

In a POST /session/login request, type the credentials in the request body according to the following JSON format:

{"username": "<controlMUser>", "password": "<controlMPassword>"}

Any additional API calls require the HTTPS header Authorization: Bearer and the token.

Copy 
Authorization: Bearer E14A4F8E45406977B31A1B091E5E04237D81C91B47AA1CE0F3FFAE252AEFE63ADE182E5702F5A9131A2DA0A8E8AE76D7C3CCBA0B7

The following example shows how to log in with cURL:

Copy 
endpoint=https://<controlmEndPointHost>:8443/automation-api
user=[USER]
passwd=[PASSWORD]
 
# 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

The following example shows how to log in with Python:

Copy 
import requests  # pip install requests if you don't have it already
import urllib3
 
urllib3.disable_warnings() # disable warnings when creating unverified requests
 
endPoint = 'https://<controlmEndPointHost>:8443/automation-api'
 
user = '[ControlMUser]'
passwd = '[ControlMPassword]'
 
# -----------------
# login
r_login = requests.post(endPoint + '/session/login', json={"username": user, "password": passwd}, verify=False)
print(r_login.content)
print(r_login.status_code)
if r_login.status_code != requests.codes.ok:
exit(1)
 
token = r_login.json()['token']
 
r = requests.get(endPoint + '/config/servers', headers={"Authorization": "Bearer "+ token}, verify=False)
print(r.content)
print(r.status_code)
exit(r.status_code == requests.codes.ok)

session logout

The session logout command enables you to log out from the user session defined by the token.

CLI Syntax

The following shows the CLI syntax for the session logout command:

ctm session logout <token>

where <token> is the token from the session login request.

REST API Syntax

The following example shows the REST API syntax for the session logout command in cURL:

Copy 
endpoint=https://<controlmEndPointHost>:8443/automation-api
token=
 
curl -g -k -H "Authorization: Bearer $token" -X POST "$endpoint/session/logout"

session user:password::update

The session user:password::update command enables you to change a password.

CLI Syntax

The following shows two CLI syntax options for the session user:password::update command:

  • ctm session user:password::update <currentPassword> <newPassword>

    The following table describes the session user:password::update command parameters.

    Parameter

    Description

    currentPassword

    Defines the existing password. The password consists of one of the following:

    • Plain text

    • Predefined Secret in the following format:

      "Secret:<secretKey>"

    newPassword

    Defines a new password. The password consists of one of the following:

    • Plain text

    • Predefined Secret in the following format:

      "Secret:<secretKey>"

  • ctm session user:password::update -p

    After you type this command, the system prompts you once for the current password and twice for the new password.

If you type both the password parameters and the -p option, the passwords that you enter through the command prompt override the passwords specified in the command.

REST API Syntax

You must provide a username and password or secret in a payload .json file for a REST API command.

The following example shows the REST API syntax for the session user:password::update command in cURL:

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

The path to the payload file is prefixed with an @ character.

The following example shows the contents of a payload .json file with the current password specified as text and the new password as a predefined secret:

Copy 
{
"user":"user1",
"currentPassword":"********",
"newPassword":"Secret:secretKey"
}