Authentication Service

The Authentication service enables you to manage authentication tokens with the following API commands:

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 and several additional token properties.

You need to provide this token in subsequent API requests.

You must define a token even in the first API request to create a new token. You can create the initial API token in Control-M Web, as described in Creating an API Token. After you create an initial token in Control-M Web, you can continue with all other token management tasks with the API.

CLI Syntax

The following shows the CLI syntax for the authentication token::create command:

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

where <tokenDefinition.json> is the full path and name of a .json payload file with token details.

The following example shows the content of a .json payload file with token details:

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

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

Parameter

Description

tokenName

Defines a unique name for the token.

expirationDate

Defines a future token expiration date in the following format:

YYYY-MM-DD

The expiration is based on the UTC time zone.

Default: No expiration (if an expiration date is not defined)

roles

Defines a list of roles that are granted access with the token.

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

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

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

REST API Syntax

The following example shows the REST API syntax for the authentication token::create command in cURL:

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

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

To select the AuthHeader value ("Authorization: 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

The following shows the CLI syntax for the authentication token::update command:

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

where <tokenDefinition.json> is the full path and name of a .json payload file with token details.

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

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

  • You must ensure that the .json file has all parameters, including those that are not updated.

    Run one of the get commands before you run an update action to obtain the current values of all parameters.

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

REST API Syntax

The following example shows the REST API syntax for the authentication token::update command in cURL:

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

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

To select the AuthHeader value ("Authorization: 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

The following shows the CLI syntax for the authentication token::delete command:

ctm authentication token::delete <tokenName>

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

REST API Syntax

The following example shows the REST API syntax for the authentication token::delete command in cURL:

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

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

To select the AuthHeader value ("Authorization: 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

The following shows the CLI syntax for the authentication token::get command:

ctm authentication token::get <tokenName>

REST API Syntax

The following example shows the REST API syntax for theauthentication token::get command in cURL:

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

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

To select the AuthHeader value ("Authorization: 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

The following shows the CLI syntax for the authentication tokens::get command:

ctm authentication tokens::get

REST API Syntax

The following example shows the REST API syntax for the authentication tokens::get command in cURL:

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

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

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