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:
{
"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:
Any additional API calls require the HTTPS header 'x-api-key': + token. For example:
The following example shows how to log in using curl:
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:
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
Log out from the user session defined by the given token.
Using CLI:
Field | Description |
|---|---|
<token> | The token obtained by the session login request |
Example using curl:
token=E14A4F8E45406977B31A1B091E5E04237D81C91B47AA1CE0F3FFAE252AEFE63ADE182E5702F5A9131A2DA0A8E8AE76D7C3CCBA0B7
curl -g -k -H "x-api-key: $token" -X POST "$endpoint/session/logout"
session user:password::update
Enables a user to change his or her own password.
CLI Syntax
Where:
Parameter | Description |
|---|---|
[currentPassword] | The user's current password, either of the following:
|
[newPassword] | A new password for the user, either of the following:
|
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
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.
-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:
"user":"user1",
"currentPassword":"********",
"newPassword":"Secret:secretKey"
}