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:

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

Field

Description

<token>

The token obtained by the session login request

Example using curl:

endpoint=https://<controlmEndPointHost>:8443/automation-api
token=E14A4F8E45406977B31A1B091E5E04237D81C91B47AA1CE0F3FFAE252AEFE63ADE182E5702F5A9131A2DA0A8E8AE76D7C3CCBA0B7

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

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

Where:

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

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.

REST API
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:

{
   "user":"user1",
   "currentPassword":"********",
   "newPassword":"Secret:secretKey"
}
Was this page helpful? Yes No Submitting... Thank you

Comments