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.

The Session token discussed in this topic was the only type of token available in previous versions of Control-M Automation API. As of version 9.0.21, BMC recommends that you create an API token using the Authentication Service, instead of using the 30-minute Session token. API tokens can be used for much longer time periods than Session tokens, based on an expiration date that you define. As soon as you create the new type of API token, you no longer need to create Session tokens. 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 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:

Copy 
> ctm session login
{
"username": "emuser",
"token": "E14A4F8E45406977B31A1B091E5E04237D81C91B47AA1CE0F3FFAE252AEFE63ADE182E5702F5A9131A2DA0A8E8AE76D7C3CCBA0B7",
"version": "9.0.21"
}
 
>ctm config servers::get -t "E14A4F8E45406977B31A1B091E5E04237D81C91B47AA1CE0F3FFAE252AEFE63ADE182E5702F5A9131A2DA0A8E8AE76D7C3CCBA0B7"

In a POST /session/login request, credentials are posted in the request body in JSON format. POST data looks like the following:

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

Any additional API calls require the HTTPS header 'Authorization: Bearer + token. For example:

Copy 
Authorization: Bearer E14A4F8E45406977B31A1B091E5E04237D81C91B47AA1CE0F3FFAE252AEFE63ADE182E5702F5A9131A2DA0A8E8AE76D7C3CCBA0B7

The following example shows how to log in using 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 using 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 logs out from the user session defined by the given token.

Using CLI:

Copy 
ctm session logout <token>

Where <token> is the token obtained by the session login request.

Example using 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 a user to change his or her own password.

CLI Syntax

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

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

Parameter

Description

[currentPassword]

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

  • Plain text.

  • Predefined Secret, with the following format: "Secret:<secretKey>".

[newPassword]

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.

REST API Syntax

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.

Copy 
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:

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