Lumen help

Managing API sessions for Edge Private Cloud

Use API calls to create sessions where you can access VMware Cloud Foundation^™ to manage clouds in your Lumen^® Edge Private Cloud service. API sessions require authorization tokens that expire after a set time. You can create authorization tokens by two methods:

using Lumen^® Private Cloud on VMware Cloud Foundation^™
creating an API session and authorization in one API call

After creating the API session, use your preferred API tool (such as Postman) to use API calls. Use any langauge compatible with REST APIs. We provide examples of calls in several popular languages (Powershell, Python, and HTTPClientModule).

VMware cloud API is outside of Lumen management. Be sure you understand how to use the API to complete your objectives. To learn more about VMware API, refer to the VMware Cloud Director API Reference Guide.

Important: Using API endpoints requires proper permissions and skills. If you are not sure about using API endpoints, contact someone in your organization who has the Organization Administrator permission within Lumen Private Cloud on VMware Cloud Foundation or create an organization administrator, if needed.

Creating an API session with basic authentication

Use an API call to create an authentication token and API session. Basic authentication requires login credentials and the API endpoints available depend on your permissions.

Creating an API session with an authentication token

Use LPC on VCF to create an authorization token which is then used to create API sessions. API sessions have restrictions based on user permissions.

Retrieving an API session

Retrieve an API session to continue working in that session or check information about the session.

Ending an API session

End an API session when you are finished. If the token is still valid, you can create a new session using that existing token and continue working.

Creating an API session with basic authentication

Note: This process requires login credentials in the request body.

To create an API session with basic authentication:

For API versions 35.2 or older, use the following POST call with your unique cloud site ID in the call:

                https://{cloud_site_id}.vcf.ctl.io/api/sessions

For API versions 36.0 or newer, use the following POST call with your unique cloud site ID in the call:

                https://{cloud_site_id}.vcf.ctl.io/cloudapi/1.0.0/sessions

The following is an example of the API call in Powershell format. This is only an example and should not be used.

In the response, the access token value ($accesstoken) contains the token used in the header for endpoints used in the API session. In this example, that token is 'X‑VMWARE‑VCLOUD‑ACCESS‑TOKEN'.

                $headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Accept", "application/json;version=36.2")
$headers.Add("Authorization", "Basic {base64encodedcredentials}")

$response = Invoke-RestMethod 'https://{cloud_site_id}.vcf.ctl.io/cloudapi/1.0.0/sessions' -Method 'POST' -Headers $headers -ResponseHeadersVariable responseHeaders 
$response | ConvertTo-Json
$accesstoken = $responseHeaders.'X-VMWARE-VCLOUD-ACCESS-TOKEN'

The following is an example of the API call in Python format. This is only an example and should not be used.

In the response, the access token value (accesstoken) contains the token used in the header for endpoints used in the API session. In this example, that token is 'X‑VMWARE‑VCLOUD‑ACCESS‑TOKEN'.

                import requests

url = "https://{cloud_site_id}.vcf.ctl.io/cloudapi/1.0.0/sessions"

payload = {}
headers = {
  'Accept': 'application/json;version=36.2',
  'Authorization': 'Basic {base64encodedcredentials}'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)
accesstoken = response.headers['X-VMWARE-VCLOUD-ACCESS-TOKEN']

The following is an example of the API call in HTTPClientModule format. This is only an example and should not be used.

In the response, the access token value (accesstoken) contains the token used in the header for endpoints used in the API session. In this example, that token is 'X‑VMWARE‑VCLOUD‑ACCESS‑TOKEN'.

                import requests

url = "https://{cloud_site_id}.vcf.ctl.io/cloudapi/1.0.0/sessions"

payload = {}
headers = {
  'Accept': 'application/json;version=36.2',
  'Authorization': 'Basic {base64encodedcredentials}'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)
accesstoken = response.headers['X-VMWARE-VCLOUD-ACCESS-TOKEN']

Creating an API session with an authentication token

Note: You must have created an authentication token.

To create an API session with an authentication token, use the following POST call with your unique cloud site ID and organization name:

                https://{cloud_site_id}.vcf.ctl.io/oauth/tenant/{{org}}/token

                $headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Content-Type", "application/x-www-form-urlencoded")

$body = "grant_type=refresh_token&refresh_token={api_access_token_from_vcd_ui}"

$response = Invoke-RestMethod 'https://{cloud_site_id}.vcf.ctl.io/oauth/tenant/{org_site_id}/token' -Method 'POST' -Headers $headers -Body $body
$response | ConvertTo-Json

$accesstoken=$response.access_token

                import requests
import json

url = "https://{cloud_site_id}.vcf.ctl.io/oauth/tenant/{org_site_id}/token"

payload = 'grant_type=refresh_token&refresh_token={vcloud_user_api_access_token}'
headers = {
  'Content-Type': 'application/x-www-form-urlencoded'
}

response = requests.request("POST", url, headers=headers, data=payload)

json.loads(response.text)

accesstoken=json.loads(response.text)['access_token']

print(response.text)

                import http.client
import json

conn = http.client.HTTPSConnection("{cloud_site_id}.vcf.ctl.io")
payload = 'grant_type=refresh_token&refresh_token={vcloud_user_api_access_token}'
headers = {
  'Content-Type': 'application/x-www-form-urlencoded'
}
conn.request("POST", "/oauth/tenant/{org_site_id}/token", payload, headers)
res = conn.getresponse()
data = res.read()

accesstoken = json.loads(data.decode("utf-8"))['access_token']
print(data.decode("utf-8"))

Retrieving an API session

To retrieve an API session, use the following GET call:

                1.0.0/sessions/current

The following is an example of the API call in Powershell format. This is only an example and should not be used.

In the header for the call, the bearer value must contain the access token received from the initial authorization call.

                $headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Accept", "application/json;version=36.2")
$headers.Add("Authorization", "Bearer {bearer_token_recieved_from_new_session}")

$response = Invoke-RestMethod 'https://{cloud_site_id}.vcf.ctl.io/cloudapi/1.0.0/sessions/current' -Method 'GET' -Headers $headers
$response | ConvertTo-Json

The following is an example of the API call in Python format. This is only an example and should not be used.

In the header for the call, the bearer value must contain the access token received from the initial authorization call.

                import requests

url = "https://{cloud_site_id}.vcf.ctl.io/cloudapi/1.0.0/sessions/current"

payload = {}
headers = {
  'Accept': 'application/json;version=36.2',
  'Authorization': 'Bearer {bearer_token_recieved_from_new_session}'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

The following is an example of the API call in HTTPClientModule format. This is only an example and should not be used.

In the header for the call, the bearer value must contain the access token received from the initial authorization call.

                import http.client

conn = http.client.HTTPSConnection("{cloud_site_id}.vcf.ctl.io")
payload = ''
headers = {
  'Accept': 'application/json;version=36.2',
  'Authorization': 'Bearer {bearer_token_recieved_from_new_session}'
}
conn.request("GET", "/cloudapi/1.0.0/sessions/current", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Ending an API session

To end an API session, use the following DELETE call:

                https://{cloud_site_id}.vcf.ctl.io/oauth/tenant/{{org}}/token

                $headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Accept", "application/json;version=36.2")
$headers.Add("Authorization", "Bearer {bearer_token_recieved_from_new_session}")

$response = Invoke-RestMethod 'https://{cloud_site_id}.vcf.ctl.io/cloudapi/1.0.0/sessions/current' -Method 'DELETE' -Headers $headers
$response | ConvertTo-Json

                import requests

url = "https://{cloud_site_id}.vcf.ctl.io/cloudapi/1.0.0/sessions/current"

payload = {}
headers = {
  'Accept': 'application/json;version=36.2',
  'Authorization': 'Bearer {bearer_token_recieved_from_new_session}'
}

response = requests.request("DELETE", url, headers=headers, data=payload)

print(response.text)

                import http.client

conn = http.client.HTTPSConnection("{cloud_site_id}.vcf.ctl.io")
payload = ''
headers = {
  'Accept': 'application/json;version=36.2',
  'Authorization': 'Bearer {bearer_token_recieved_from_new_session}'
}
conn.request("DELETE", "/cloudapi/1.0.0/sessions/current", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))