How do I connect to the cloud API

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 Tanzu Salt. You can find the Tanzu Salt version in the Master Plugins workspace.

3. Create a job in Tanzu Salt. 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.

   

3. Complete the form.

   

   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 Tanzu Salt service, search for the Tanzu Salt service, and select the desired service role. For a list of available service roles, see How do I define user roles.

      a. (Optional) Set an email preference to receive a reminder when your token is about to expire. b. 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 Tanzu Salt 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": []
   }'
   

   Region	Tanzu Salt 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

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.