As a systems administrator, you can use the cloud API to programatically complete common infrastructure administration tasks, such as assign permissions to a role or user, create or update a job, or view job returns. You can install sseapiclient in an environment with a Salt master or an environment without a Salt master.

Before you start

Before you use sseapiclient, complete the following prerequisites:

  1. If you are using sseapiclient in an environment with a Salt master:
    1. If you have not installed the Master Plugin on your Salt master, see Install and configure the Master Plugin for installation instructions. sseapiclient is bundled with the Master Plugin and is installed when you install the plugin.
    2. Verify that you installed version 8.11.1 or later of the Master Plugin on your Salt master. You can find the Master Plugin version in the Master Plugins workspace.

      You can also update the Master Plugin on your Salt master through the Master Plugins workspace. See Using the Master Plugins workspace for more information.

  2. If you are using sseapiclient in an environment without a Salt master:
    1. Run the following commands to install the Pika Python and the PyJWT libraries on your device:
      pip3 install pika==1.3.1
pip3 install pyjwt==2.4.0
    2. Download the latest version of sseapiclient from the Master Plugins workspace. Then run the following command to install sseapiclient on your device:
      pip3 install SSEApiClient-file-name.whl

      See Using the Master Plugins workspace for more information.

    3. Verify that the sseapiclient version matches the version of Automation Config. You can find the Automation Config version in the Master Plugins workspace.
  3. Create a job in Automation Config. See How do I create jobs for more information.

Generate an API token

Before you can connect to the cloud API, you must generate an API token using the Cloud Services Console. The token is used to authenticate your Salt master with VMware Cloud Services.

  1. On the Cloud Services Console toolbar, click your user name and select My Account > API Tokens.
  2. Click Generate Token.

    API tokens page in CSP

  3. Complete the form.

    Generate token form in CSP

    1. Enter a name for the token.
    2. Select the token's Time to Live (TTL). The default duration is six months.
      Note: A non-expiring token can be a security risk if compromised. If this happens, you must revoke the token.
    3. Define scopes for the token.
      Scope Description
      Service roles

      Service roles are built-in, pre-defined sets of permissions that grant access to VMware Cloud services.

      To access the Automation Config service, search for the Automation Config service, and select the desired service role. For a list of available service roles, see How do I define user roles.
    4. (Optional) Set an email preference to receive a reminder when your token is about to expire.
    5. Click Generate.

      The newly generated API token appears in the Token Generated window.

  4. Save the token credentials to a secure location.

    After you generate the token, you will only be able to see the token's name on the API Tokens page, not the credentials. To regenerate the token, click Regenerate.

  5. Click Continue.

Make an API call

After you generate an API token, you can make an API call using sseapiclient or cURL.

To make an API call:

  1. Log in to the environment where you installed sseapiclient.
  2. Run the following command, replacing the server value with your region-specific Automation Config URL and the API token value with the API token you generated previously. The following code samples show an API call in the US region.
    Python 
    from sseapiclient import APIClient
client = APIClient(server='https://ssc-gateway.mgmt.cloud.vmware.com', csp_api_token='<api-token>')

client.api.job.get_jobs()
    cURL 
    SERVER="https://ssc-gateway.mgmt.cloud.vmware.com" && \
API_TOKEN="<api-token>" && \
BEARER_TOKEN=$(curl --silent 'https://console.cloud.vmware.com/csp/gateway/am/api/auth/api-tokens/authorize' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode "api_token=$API_TOKEN" \
| grep -o '"access_token":"[^"]*' | grep -o '[^"]*$') && \
XSRFTOKEN=$(curl -s -I -X POST "$SERVER/account/login/" \
--header "Authorization: Bearer $BEARER_TOKEN" \
| awk '/X-XSRFTOKEN:|x-xsrftoken:/ {gsub("\r","",$2);print $2}') && \
curl --location --request POST "$SERVER/rpc" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $BEARER_TOKEN" \
--header "X-XSRFTOKEN: $XSRFTOKEN" \
--header "Cookie: _xsrf=$XSRFTOKEN; _xsrf=$XSRFTOKEN" \
--data '{
    "resource": "job",
    "method": "get_jobs",
    "kwarg": {},
    "args": []
}'
    Table 1. Regional URLs for Automation Config
    Region Automation Config URL
    US https://ssc-gateway.mgmt.cloud.vmware.com
    Germany https://de.ssc-gateway.mgmt.cloud.vmware.com
    India https://in.ssc-gateway.mgmt.cloud.vmware.com
    Canada https://ca.ssc-gateway.mgmt.cloud.vmware.com
    Australia https://au.ssc-gateway.mgmt.cloud.vmware.com
    UK https://uk.ssc-gateway.mgmt.cloud.vmware.com

Results

The jobs.get_jobs() endpoint returns a list of all jobs. The following code samples show an example successful response.
Python 
RPCResponse(riq=3, ret={'count': 1, 'results': [{'uuid': '60c14cfc-09ca-4b5a-bc76-8294287c2e6c',
 'name': 'Check disk usage', 'desc': 'Checks disk usage on targeted devices', 'cmd': 'local',
 'tgt_uuid': '7f93b928-388b-11e6-b133-346895ecb8f3', 'fun': 'disk.usage', 'arg': {'arg': [], 'kwarg':
 {}}, 'masters': [], 'metadata': {'auth': {'owner': {'uuid': '8964e9f3-6864-4fe5-ba4a-ab4530caa8ca',
 'config_name': 'internal', 'username': 'root'}, 'access': {}}}, 'tgt_name': 'CentOS'}], 'limit': 50},
 error=None, warnings=[])
cURL 
{'riq': 3, 'ret': {'count': 1, 'results': [{'uuid': '60c14cfc-09ca-4b5a-bc76-8294287c2e6c',
 'name': 'Check disk usage', 'desc': 'Checks disk usage on targeted devices', 'cmd': 'local',
 'tgt_uuid': '7f93b928-388b-11e6-b133-346895ecb8f3', 'fun': 'disk.usage', 'arg': {'arg': [], 'kwarg':
 {}}, 'masters': [], 'metadata': {'auth': {'owner': {'uuid': '8964e9f3-6864-4fe5-ba4a-ab4530caa8ca',
 'config_name': 'internal', 'username': 'root'}, 'access': {}}}, 'tgt_name': 'CentOS'}], 'limit': 50}, 'error': null, 'warnings': []}
Note: Some functions require administrative privileges, such as client.api.admin.trim_database(). If you do not have sufficient permissions, the API throws an error.

To use administrative functions, you can generate a new API token and select the Superuser service role.

What to do next

Read the API (RaaS) documentation on the VMware Developer Portal to learn more about available resources.