Authentication Service

The Authentication service enables you to manage authentication tokens for running API commands.

The following API commands enable you to manage authentication tokens:

authentication token::create

The authentication token::create command enables you to create an authentication token for the logged-in user.

A successful response returns a token value, as well as several additional token properties.

You specify this token in subsequent API requests.

You must specify a token even in the API request for creation of a new token. Therefore, to create your very first API token, you can choose one of the following methods:

  • Specify a Session token, as described in Session Service or in Authentication Tokens.

  • Create your very first API token through the Control-M user interface, as described in Creating an API Token. After creating an initial token through the UI, you can proceed with all other token management tasks through the API.

As soon as you have an API token, you no longer need to create Session tokens (the only type of token available in previous versions of Control-M Automation API).

CLI Syntax

Copy 
ctm authentication token::create  -f <tokenDefinition.json>

Where <tokenDefinition.json> is the full path and name of a .json payload file that contains token details. Here is an example for the content of this file:

Copy 
{
"tokenName": "emuser1-token",
"expirationDate":"2020-12-02",
"roles": ["Admin","User"]
}

The following table describes the authentication token::create command parameters.

Parameter

Description

tokenName

A unique name for the token

expirationDate

A future date when the token will expire, in YYYY-MM-DD format

Expiration is based on the UTC timezone.

If you do not specify this property, the default is no expiration.

roles

A list of roles for which the token grants access

The logged-in user must be a member of all specified roles.

This parameter is mandatory, that is, you must specify at least one role.

If annotation is enabled for the Scheduling definitions, Configuration management, or Control-M security category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

Example using cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type: application/json" -X POST "$endpoint/authentication/token" -d @tokenDefinition.json

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

authentication token::update

The authentication token::update command enables you to update an authentication token of the logged-in user.

A successful response returns an updated list of token properties.

CLI Syntax

Copy 
ctm authentication token::update -f <tokenDefinition.json>

Where <tokenDefinition.json> is the full path and name of a .json payload file that contains token details.

The contents of this file for an update request are the same as for a creation request (authentication token::create). Note the following guidelines for an update action:

  • You can update the expiration date of the token and the roles associated with the token. You cannot modify the name of the token.

  • All parameters must be included in the .json file, even those that you are not updating.

    To obtain current values of all parameters, you can use one of the get commands before running an update action.

If annotation is enabled for the Scheduling definitions, Configuration management, or Control-M security category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

Example using cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type: application/json" -X PUT "$endpoint/authentication/token" -d @tokenDefinition.json

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

authentication token::delete

The authentication token::delete command enables you to delete an authentication token of the logged-in user.

CLI Syntax

Copy 
ctm authentication token::delete <tokenName>

If annotation is enabled for the Scheduling definitions, Configuration management, or Control-M security category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

Example using cURL:

Copy 
tokenName=myToken
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type: application/json" -X DELETE "$endpoint/authentication/token/$tokenName"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

authentication token::get

The authentication token::get command enables you to retrieve details of an authentication token of the logged-in user.

CLI Syntax

Copy 
ctm authentication token::get <tokenName>

REST API Syntax

Example using cURL:

Copy 
tokenName=myToken
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type: application/json" "$endpoint/authentication/token/$tokenName"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

authentication tokens::get

The authentication tokens::get command enables you to retrieve a list of authentication tokens for the logged-in user, including the details of each token.

CLI Syntax

Copy 
ctm authentication tokens::get

REST API Syntax

Example using cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type: application/json" "$endpoint/authentication/tokens"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.