Control-M Automation API Authorizations

Through Control-M, you can control the access levels that each of your defined roles has to the various API functionalities and services. The following series of tables summarize the access levels that are required for the various API commands. You set these access levels through the role definitions in the Configuration domain.

Session Service Authorizations

The following table lists the Interface Access categories required by the API Session service. You set these access levels through the role definitions in the Configuration domain, on the General tab.

API Functions

Interface Access Category

Log in and get an access token

  • session login

  • session logout

Automation API

Alternatively, for product versions earlier than 9.0.20 or when using Compatibility mode:

Control-M Configuration Manager

Control-M Desktop, Utilities and EM API

Authentication Service Authorizations

To use the Authentication service to create, update, delete, or get details of your own tokens, you must have the Automation API interface access category. You set this access category through the role definitions in the Configuration domain, on the General tab.

To use the Authentication service to control authentication tokens of other users, an administrator must have the following role access levels. You set these access levels through the role definitions in the Configuration domain, on the Access Control tab.

API Functions

Access Control Category

Access Level

Retrieve token details

  • authentication token::get

  • authentication tokens::get

Configuration > Admin Management > Authorizations/Users&Roles

Browse

Create or update a token

  • authentication token::create

  • authentication token::update

Configuration > Admin Management > Authorizations/Users&Roles

Update

Delete a token

  • authentication token::delete

Configuration > Admin Management > Authorizations/Users&Roles

Full

Configuration Service Authorizations

The following table lists the role access levels required by the various API functions in the Config service. You set these access levels through the role definitions in the Configuration domain, on the Access Control tab.

If the access levels defined through Configuration > Admin Management differ from (that is, are higher or lower than) those defined in the other Configuration categories, such as Configuration > Agents or Configuration > Plug-ins, or Configuration > Run as Definition, then the definitions in Admin Management take precedence.

API Functions

Access Control Category

Access Level

Access Agent topology information

  • config server:agents::get

  • config server:agentlesshosts::get

  • config server:remotehosts::get

Configuration > Agents

None

Access Control-M/Server topology information

  • config servers::get

Configuration > Admin Management > Configuration

Browse

Access Agent information

  • config server:agent::analysis

  • config server:agent:crt:expiration::get

  • config server:hostgroups:agents::get

Configuration > Agents

Browse

Access detailed Agent configuration information

  • config server:agent:params::get

  • config server:agent:param::set

  • config server:agentlesshost::get

  • config server:remotehost::get

  • config server:hostgroups::get

  • config server:hostgroup:agents::get

  • config server:hostgroup::update

Configuration > Agents

Full

Add or update Control-M/Server configurations

  • config server::add

Configuration > Admin Management > Configuration

Update

Add or update Agent configurations

  • config server:agent::add

  • config server:agent::update

  • config server:agent::disable

  • config server:agent::enable

  • config server:agent::ping

  • config server:agent:csr::create

  • config server:agent:crt::deploy

  • config server:hostgroup:agent::add

  • config server:agentlesshost::add

  • config server:remotehost::add

  • config item::recycle

Configuration > Agents

Update

Add or update Run as User configurations

  • config server:runasuser::add

  • config server:runasuser::update

Configuration > Run as Definition

Update

Access Run as User configuration details

  • config server:runasuser::get

  • config server:runasuser::test

  • config server:runasusers::get

Configuration > Run as Definition

Browse

Delete Control-M/Server configuration

  • config server::delete

Configuration > Admin Management > Configuration

Full

Delete Agent configuration

  • config server:agent::delete

  • config server:agentlesshost::delete

  • config server:remotehost::delete

  • config server:hostgroup:agent::delete

  • config server:hostgroup::delete

Configuration > Agents

Full

Delete Run as User configuration

  • config server:runasuser::delete

Configuration > Run as Definition

Full

Perform High Availability actions

  • config server::failover

  • config server::setasprimary

  • config em::failover

  • config em::setasprimary

  • config em::fallback

Configuration > Admin Management > Configuration

Update

Get High Availability status

  • config em:highavailabilitystatus::get

Configuration > Admin Management > Configuration

Browse

Access detailed Job Archiving configuration

  • config archive:rules::get

  • config archive:statistics::get

Configuration > Admin Management > Configuration

Browse

Manage configurations of Job Archiving

  • config archive:rule::add

  • config archive:rule::update

  • config archive:rule::delete

  • config archive::cleanup

Configuration > Admin Management > Configuration

Update

Access configurations of file transfers to and from external users (using Control-M MFT Enterprise B2B)

  • config mfte:site:hub:status::get

  • config mfte:site:gateways::get

  • config mfte:site:virtualfolders::get

  • config mfte:site:externalusers::get

  • config mfte:site:externaluser:virtualfolders::get

  • config mfte:site:externalusers:locked::get

  • config mfte:site:usergroups::get

Configuration > Plug-ins

Browse

Add or update configurations for Control-M MFT Enterprise B2B

  • config mfte:site:cluster:hub::add

  • config mfte:site:gateway::add

  • config mfte:site:virtualfolder::add

  • config mfte:site:virtualfolder::update

  • config mfte:site:virtualfolder:user::add

  • config mfte:site:virtualfolder:user::remove

  • config mfte:site:externaluser::add

  • config mfte:site:externaluser::update

  • config mfte:site:externaluser::lock

  • config mfte:site:externaluser::unlock

  • config mfte:site:externalusers::unlock

  • config mfte:site:usergroup::add

  • config mfte:site:usergroup::update

Configuration > Plug-ins

Update

Delete configurations for Control-M MFT Enterprise B2B

  • config mfte:site:cluster:hub::delete

  • config mfte:site:gateway::delete

  • config mfte:site:virtualfolder::delete

  • config mfte:site:externaluser::delete

  • config mfte:site:usergroup::delete

Configuration > Plug-ins

Full

Access configurations of file transfers to and from remote hosts (using Control-M MFT)

  • config server:agent:mft:pgptemplates::get

  • config server:agent:mft:zostemplates::get

  • config server:agent:mft:configuration::get

  • config server:agent:mft:fts:settings::get

Configuration > Plug-ins

Browse

Add or delete configurations for Control-M MFT

  • config server:agent:mft:pgptemplate::add

  • config server:agent:mft:pgptemplate::delete

  • config server:agent:mft:zostemplate::add

  • config server:agent:mft:zostemplate::delete

Configuration > Plug-ins

Full

Update configurations for Control-M MFT

  • config server:agent:mft:pgptemplate::update

  • config server:agent:mft:zostemplate::update

  • config server:agent:mft:configuration::update

  • config server:agent:mft:fts:settings::update

Configuration > Plug-ins

Update

Manage SSH settings for Control-M MFT

  • config server:agent:mft:ssh:key::generate

  • config server:agent:mft:ssh:host::authorize

  • config server:agent:mft:ssh:cluster::authorize

Configuration > Admin Management > Security

Full

Access details of roles, users, and LDAP groups

  • config authorization:role::get

  • config authorization:roles::get

  • config authorization:user::get

  • config authorization:users::get

  • config authorization:ldap:roles::get

  • config authorization:role:associates

  • config authorization:organizationgroup:roles::get

  • config authorization:organizationgroups::get

  • config authorization:organizationuser:roles::get

  • config authorization:organizationusers::get

Configuration > Admin Management > Authorizations/Users & Roles

Browse

Manage authorizations of roles, users, and LDAP groups

  • config authorization:role::add

  • config authorization:role::update

  • config authorization:role::rename

  • config authorization:user::add

  • config authorization:user::update

  • config authorization:user::simulate

  • config authorization:user:role::add

  • config authorization:user:role::delete

  • config authorization:ldap:role::add

  • config authorization:ldap:role::delete

  • config authorization:organizationgroup::simulate

  • config user:password::adminUpdate

Configuration > Admin Management > Authorizations/Users & Roles

 

For simulation functions, also:

Configuration > Admin Management > Configuration

Update

Delete authorizations of roles and users

  • config authorization:role::delete

  • config authorization:user::delete

Configuration > Admin Management > Authorizations/Users & Roles

Full

Access details of system settings

  • config systemsettings::get

  • config systemsettings:identityprovidermetadata::get

Configuration > Admin Management > Configuration

Browse

Add or update system settings

  • config systemsettings::set

Configuration > Admin Management > Configuration

Update

Access details of secrets in the Control-M vault

  • config secrets::get

Tools > Secrets

Browse

Add or update secrets in the Control-M vault

  • config secret::add

  • config secret::update

Tools > Secrets

Update

Delete secrets in the Control-M vault

  • config secret::delete

Tools > Secrets

Full

Provision Service Authorizations

The following table lists the role access levels required by the various API functions in the Provision service. You set these access levels through the role definitions in the Configuration domain, on the Access Control tab.

If the access levels defined through Configuration > Admin Management differ from (that is, are higher or lower than) those defined in the other Configuration categories, such as Configuration > Agents or Configuration > Run as Definition, then the definitions in Admin Management take precedence.

API Functions

Access Control Category

Access Level

Access details of provisioned agents

  • provision images

Configuration > Agents

Browse

Provision a new agent

  • provision agent::setup

  • provision agent::install

  • provision image

Configuration > Agents

Update

Undo the provisioning of an agent

  • provision image::remove

  • provision agent::uninstall

Configuration > Agents

Full

Upgrade an existing agent and deploying plug-ins

  • provision upgrade::install

  • provision upgrade::uninstall

  • provision upgrade:output::get

  • provision upgrade::retry

  • provision upgrade::delete

  • provision upgrade::cancel

Configuration > Agents

Full

Access details of agent upgrades

  • provision upgrade::get

  • provision upgrades::get

  • provision upgrades:agents::get

  • provision upgrades:versions::get

Configuration > Agents

Browse

Provision a Control-M/Server

  • provision server::setup

  • provision server::install

Configuration > Agents

and

Configuration > Run as Definition

Update

Build and Deploy Service Authorizations

The following table lists the role access levels required by the various API functions in the Build and Deploy services. You set these access levels through the role definitions in the Configuration domain, on the Access Control tab.

If the access levels defined through Configuration > Admin Management differ from (that is, are higher or lower than) those defined in the other Configuration categories, such as Configuration > Connection Profiles, then the definitions in Admin Management take precedence.

API / API Service

Access Control Category

Access Level

Build jobs definitions

  • build <definitionsFile>

Access tokens are enough.

Retrieve deployed job definitions

  • deploy jobs::get

Planning > Folders and Jobs

Browse level on all retrieved folders

  • Server: All

  • Folder Name: *

  • Access Level: Browse

Deploy definitions of Control-M objects

  • deploy <definitionsFile>

  • deploy poll

 

 

 

Planning > Folders and Jobs

Update level on all folders deployed

  • Server: All

  • Folder Name: *

  • Access Level: Update

Planning > Run as

Grant permission to write jobs that Run as use on specific hosts as required by all jobs deployed.

  • Server: All

  • Run as Name or Pattern: *

  • Agent/Host Group: *

Tools > Calendars

Update level on all calendars deployed

  • Server: All

  • Calendar Name: *

  • Access Level: Update

Tools > Site Standards

Update level for all site standards deployed.

Update level for site standard policies.

Configuration > Connection Profiles

Full level on all connection profiles deployed if you plan to create new connection profiles. Update level if you only want to modify existing connection profiles.

  • Server: All

  • Name: *

  • Access Level: Full or Update

Delete deployed objects

  • deploy folder::delete

  • deploy subfolder::delete

  • deploy job::delete

Planning > Folders and Jobs

Full access level on all folders to delete

  • Server: All

  • Folder Name: *

  • Access Level: Full

Deploy AI job type

  • deploy ai:jobtype

Tools > Application Integrator

Full

Retrieve details of deployed AI job types

  • deploy ai:jobtypes::get

Deploy Control-M integration plug-ins

  • deploy jobtype

Tools > Application Integrator

Browse

Retrieve deployed calendar definitions

  • deploy calendars::get

Tools > Calendars

Browse access level on all calendars to retrieve

  • Server: All

  • Calendar Name: *

  • Access Level: Browse

Delete a deployed calendar

  • deploy calendar::delete

Tools > Calendars

Full access level on all calendars to delete

  • Server: All

  • Calendar Name: *

  • Access Level: Full

Retrieve details of deployed connection profiles

  • deploy connectionprofiles:centralized::get

  • deploy connectionprofiles:centralized:status::get

  • deploy connectionprofile:centralized::deploymentstatus

  • deploy connectionprofiles:local::get

Configuration > Connection Profiles

Browse access level on all connection profiles to retrieve

  • Server: All

  • Name: *

  • Plug-in Type: All Plug-ins

  • Access Level: Browse

Delete deployed connection profiles

  • deploy connectionprofile:centralized::delete

  • deploy connectionprofile:local::delete

Configuration > Connection Profiles

Full access level on all connection profiles to delete

  • Server: All

  • Name: *

  • Plug-in Type: All Plug-ins

  • Access Level: Full

Test deployed connection profiles

  • deploy connectionprofile::test

Retrieve details of site standards and site standard policies

  • deploy sitestandards::get

  • deploy sitestandards:details::get

  • deploy sitestandardpolicies:details::get

Tools > Site Standards

Browse level for all site standards deployed.

Browse level for site standard policies.

Add site standard policies

  • deploy sitestandardpolicies::add

Tools > Site Standards

Update level for site standard policies.

Rename or delete site standards or site standard policies

  • deploy sitestandard::rename

  • deploy sitestandard::delete

  • deploy sitestandardpolicy::rename

  • deploy sitestandardpolicy::delete

Tools > Site Standards

Full level for all site standards deployed.

Full level for site standard policies.

Run Service Authorizations

The following table lists the role access levels required by the various API functions in the Run service. You set these access levels through the role definitions in the Configuration domain, on the Access Control tab.

API

Access Control Category

Access Level

Access job status and details

  • run status

  • run job:status::get

  • run jobs:status::get

  • run job:statistics::get

  • run job::waitingInfo

  • run job::get

Monitoring > Job Permissions

All View options for all jobs.

Perform job actions

  • run job::confirm

  • run job::delete

  • run job::free

  • run job::hold

  • run job::kill

  • run job:log::get

  • run job:output::get

  • run job::rerun

  • run job::runNow

  • run job::setToOk

  • run job::undelete

  • run job::modify

Monitoring > Job Permissions

All Actions and View options for all relevant jobs.

Run Jobs definition file

  • run <jobDefinitionsFile>

  • run ondemand

Planning > Folders and Jobs

Update level on all folders deployed

  • Server: All

  • Folder Name: *

  • Access Level: Update

  • Run checkbox selected
 

Planning > Run as

Grant permission to write jobs that Run as a user on specific hosts, as required by all jobs deployed.

  • Server: All

  • Run as Name or Pattern: *

  • Agent/Host Group: *

Order a deployed folder and jobs

  • run order

Planning > Folders and Jobs

Update level on all folders deployed

  • Server: All

  • Folder Name: *

  • Access Level: Update

  • Run checkbox selected

Retrieve events

  • run events::get

Tools > Events

Browse level for events retrieved

  • Server: All

  • Event Name: *

  • Access Level: Browse

Add an event

  • run event::add

Tools > Events

Update level for events to add

  • Server: All

  • Event Name: *

  • Access Level: Update

Delete an event

  • run event::delete

Tools > Events

Full access level for events to delete

  • Server: All

  • Event Name: *

  • Access Level: Full

Retrieve resources

  • run resources::get

Tools > Resource Pool

At lease Browse level for Resource Pools retrieved

  • Server: All

  • Resource Name: *

  • Access Level: Browse

 

Tools > Lock Resources

At lease Browse level for Lock Resources retrieved

  • Server: All

  • Resource Name: *

  • Access Level: Browse

Add/update a resource

  • run resource::add

  • run resource::update

Tools > Resource Pool

Update level for Resource Pools updated

  • Server: All

  • Resource Name: *

  • Access Level: Update

Delete a resource

  • run resource::delete

Tools > Resource Pool

Full level for Resource Pools deleted

  • Server: All

  • Resource Name: *

  • Access Level: Full

Retrieve Workload Policy details

  • run workloadpolicies:detailed::get

  • run workloadpolicies::get

Tools > Workload Policies

Browse

Add and control Workload Policies

  • run workloadpolicies::add

  • run workloadpolicy::activate

  • run workloadpolicy::deactivate

Tools > Workload Policies

Update

Delete a Workload Policy

  • run workloadpolicy::delete

Tools > Workload Policies

Full

Retrieve pool variable details

  • run variables::get

Tools > Pool Variables

Browse

Define or update pool variables

  • run variables::set

Tools > Pool Variables

Update

Delete pool variables

run variables::delete

Tools > Pool Variables

Full

Access the status of alert streaming

  • run alerts:stream::status

Alerts

Browse

Update alerts

  • run alerts::update

  • run alerts:status::update

Alerts

Update