Anyware Manager offers a RESTful API as an alternative to using the Anyware Manager Admin Console. It allows for programmatic management and automation of resources in Anyware Manager deployments. The API can be used to create, configure, and manage Anyware Manager resources including deployments, connectors, and workstations (with a PCoIP agent installed). In addition it enables the entitlement of users to machines and power management on supported platforms. Currently Anyware Manager supports resource management on private (on-premises) clouds, Microsoft Azure, Amazon Web Services (AWS), and Google Cloud (GCP).

To better understand how Anyware Manager deploys and manages resources on clouds, please refer to Anyware Manager architecture documents.

All operations accept either query parameters or JSON request bodies and are authorized (excluding initial authentication) using JWTs (JSON Web Tokens). Operations return JSON responses following the JSend specification.

The root endpoint for Anyware Manager API v1 is: https://cam.teradici.com/api/v1/

Dates and timestamps follow the ISO 8601 standard.
An example:

• 2019-11-15T18:50:46.651Z

If a date is updated using '2019-11-15', Anyware Manager will record it as '2019-11-15T00:00:00.000Z'.
If a date is updated using '2019-11', Anyware Manager will record it as '2019-11-01T00:00:00.000Z'.

Anyware Manager API usage is limited on a per-IP basis, and this rate limiting is calculated across all Anyware Manager APIs.
Current rate limiting:

• 50 request/second per IP address

Requests exceeding any of the above limitations will return an HTTP 429 error:

  {"code":429, "status":"retry", "data":{"reason":"429 - Rate Limit Exceeded - Review Policy Here: https://cas.teradici.com/api/docs#section/Getting-Started/API-Rate-Limiting"}}

Clients should account for the specified rate limits and be able to gracefully handle 429 errors by delaying further requests.

Anyware Manager provides the following methods for API requests:

• GET used to retrieve resources
• POST used to create resources
• PUT used to update resources
• DELETE used to delete resources

Note: Anyware Manager API uses URL-path and request body to receive query parameters. GET methods generally use URL query strings to send parameters and an example is presented in Add a remote workstation. Other methods may require parameters to be sent in the request body, and an example is shown in Create a connector. Please refer to instructions under each API.

A list of common status codes in Anyware Manager API v1:

• 200 A successful request. 200 code will be returned in response to successful GET, PUT and DELETE requests.
• 201 Your resource was created successfully. 201 code will be returned in response to successful POST requests.
• 400 Invalid request. API requests lacking of appropriate parameters will return HTTP 400.
• 401 Unauthorized request. Anyware Manager APIs generally require a valid JWT to be provided in the authorization header; if that token is missing or expired, an API request will return HTTP 401.
• 403 You do not have the required permissions. API requests without required permission will return HTTP 403.
• 404 Resource does not exist. If the resources you want to update/delete do not exit, Anyware Manager will return HTTP 404.
• 409 Conflict. Trying to create a duplicate resource (such as having the same unique value) will return HTTP 409.
• 412 Precondition Failed. If the access to the target resource has been denied, an API request will return HTTP 412.
• 413 Payload Too Large. If the request body size is exceeded, Anyware Manager will return HTTP 413.
• 429 Too Many Requests. If API requests exceed the defined rate limit, Anyware Manager will return HTTP 429.
• 500 Internal server error. Anyware Manager server/database malfunction will return HTTP 500.

To access and use the Anyware Manager APIs, you must be a member of Teradici Advantage Partner Program or have been pre-approved by Teradici. Contact Teradici for more information.

An Anyware Manager Service Account allows you to create a deployment and at most ONE Deployment Key for each deployment it creates. This key can then be used to create more Deployment Keys and interact with the deployment and the resources under that deployment.

You can create an Anyware Manager service account from within the Anyware Manager Admin Console by following these steps:

1. Click on your account name and select Anyware Manager service account.

2. Click the + icon from the Anyware Manager service account page and name your new account.

3. Once you have created the Anyware Manager service account download the JSON file or copy the key ID. Ensure that you store the file securely as this key cannot be recovered if lost.
4. Learn from this example of how to use the Anyware Manager Service Accounts you just created.

Prior to using the Anyware Manager APIs, a Deployment and associated Deployment Service Account must be created. If you already have an existing Deployment and a Deployment Service Account, proceed to the examples section.

1. Sign in to Anyware Manager

Go to the Anyware Manager Admin Console and sign in.

2. Create a Deployment

If you have never signed in to the Anyware Manager Admin Console before, you will be prompted to create a default deployment and enter your registration code and click unlock.

Once you have unlocked the console or if you have already created a deployment, in the top bar Deployments kebab menu select edit Deployment to create a Deployment Service Account.

3. Create a Deployment Service Account

Click on the menu icon on the side of the deployment you want to generate a Deployment Service Account key for and click edit. At the bottom of the page, there is a section for Deployment Service Accounts. To add a new Deployment Service Account Key, click the Add icon next to the text.

Once the Deployment Service Account key has been generated, a modal will inform you to copy out the credentials. These are the credentials used to sign in and use the Anyware Manager API. Make sure you save these somewhere as they cannot be recovered once the window is closed.
Note: Every Deployment Service Account is associated to one deployment.

The response contains the credentials for the service account. These credentials should be saved and used to sign in to Anyware Manager and obtain a token to authorize further requests.

The examples use Python and the requests library. Execute the cells in order for each example to test common operations using the Anyware Manager API.

  import requests
  import pprint

  api_url = "https://cam.teradici.com/api/v1"

Use the credentials you obtained from the Anyware Manager Admin Console in the prerequisites section to sign in and authenticate, which provides an authorization token scoped to the associated deployment. This token will be used for all API operations and is valid for one hour, after which it will expire and a new token can be generated by signing in again.

  # Paste your credentials into the variable below
  credentials = {"username":"-----","apiKey":"-----","deploymentId":"-----","tenantId":"-----"}

  request_body = dict(username=credentials.get('username'),
              password=credentials.get('apiKey'),
              tenantId=credentials.get('tenantId'))

  response = requests.post("{}/auth/signin".format(api_url),
  json=request_body)

  if not response.status_code == 200:
      raise Exception(response.text)
  response_body = response.json()

  auth_token = response_body.get('data').get('token')

  """
  There are two options to get a valid token:
  (1) Generate a token programmatically, just like in the example above. This token was created using
  a service account, and only works for the deployment associated with that service account.
  (2) Get a token from Anyware Manager Admin Console. This token has a tenant scope, which means it works
  for all deployments.
  """

  # Create session object; all subsequent requests using the session
  # will have the authorization header set
  session = requests.Session()

  session.headers.update({"Authorization": auth_token})

  pprint.pprint(auth_token)

Once you have signed in, you have access to the Deployment associated with the Service Account. It can be retrieved from /deployments and the deploymentId can be passed in to other API operations.

  # A valid deploymentId is required to generate this token
  # The deploymentId can be fetched by listing all deployments
  response = session.get("{}/deployments".format(api_url))

  if not response.status_code == 200:
      raise Exception(response.text)
  response_body = response.json()

  # The service account only has access to its one associated
  # deployment, so we get element 0
  deployment = response_body.get('data')[0]

  deployment_id = deployment['deploymentId']

  pprint.pprint(deployment_id)

Prior to adding machines and entitlements, an Anyware Connector is required to handle brokering. Setting up an Anyware Connector requires two steps: first, generate a connector token, then install the connector.

3.1 Generate a connector token

In order to deploy an Anyware Connector you need to have a connector token, which associates an installed connector to a deployment. Once generated, the token will expire after one hour. If it expires, a new one can be generated by again calling the following API.

  body = dict(
      deploymentId=deployment_id,
      connectorName='connector0', # <- Enter your desired connector name here
  )

  response = session.post("{}/auth/tokens/connector".format(api_url), json=body)

  if not response.status_code == 200:
      raise Exception(response.text)
  response_body = response.json()

  connector_token = response_body.get('data').get('token')

  pprint.pprint(connector_token)

3.2 Install a Connector

Once you have generated a connector token, you can install a connector by following the installation guide. Alternatively, you can install the connector using these example Terraform scripts or pass the token to existing automation you may have.

3.3 Get the Connector

Once it's installed, you can query the API for the connector's health status.

  response = session.get("{}/deployments/connectors".format(api_url))

  if not response.status_code == 200:
      raise Exception(response.text)
  response_body = response.json()

  connectors = response_body.get('data')

  pprint.pprint(connectors)

If you have an existing Remote Workstation joined to a domain controller and reachable by the connector you created previously, you can add it to Anyware Manager using these APIs.

4.1 Find an existing computer

The connector syncs computer records from Active Directory to Anyware Manager. All machines that are currently joined to the configured AD domain controller can be retrieved using the /adcomputers API.

  # Set the limit to retrieve more machines and the offset to shift the page
  # If you add computerName to the query params you can query a specific
  # machine ('computerName': {name})

  params = {'limit': 1, 'offset': 0, 'deploymentId': deployment_id}

  response = session.get("{}/machines/entitlements/adcomputers".format(api_url), params=params)

  """
  The above code is equivalent to
  response = session.get("{}/machine/entitlements/adcomputers?limit=1&offset=0&deploymentId={}".format(api_url, deployment_id))
  """

  if not response.status_code == 200:
      raise Exception(response.text)
  response_body = response.json()

  ad_computers = response_body.get('data')

  pprint.pprint("Total Computers: {}".format(response_body.get('total')))

  pprint.pprint(ad_computers)

  if ad_computers:
      machine_name = ad_computers[0]['computerName']
  else:
      raise Exception('No computers!')

4.2 Add a Remote Workstation

Once you have identified the machine you want to use, you can use the API to add a machine resource to Anyware Manager. When adding existing remote workstations (machines that have been deployed and joined to the domain), use the managed=False and provider="onprem" body parameters. This will ensure that Anyware Manager does not try to power manage the machine.

  body = dict(
      machineName= machine_name,
      deploymentId=deployment_id,
      provider='onprem',
      managed=False,
  )

  response = session.post("{}/machines".format(api_url), json=body)

  if not response.status_code == 201:
      raise Exception(response.text)
  response_body = response.json()

  machine = response_body.get('data')

  pprint.pprint(machine)

  machine_id = machine['machineId']

User entitlements associate a Directory User to a Remote Workstation, and are required for brokering. The userGuid from the directory service is used to associate the actual user to the remote workstation.

5.1 Query AD users

First we need to retrieve the list of "Active Directory Users (adusers)" in order to extract the userGuid for the user we are looking for, which can be done through the /adusers API.

  # Set the limit to retrieve more machines and the offset to shift the page
  # If you add name to the query params you can query a specific user by name
  # ('name': {name})

  params = {'limit': 1, 'offset': 0, 'deploymentId': deployment_id}

  response = session.get("{}/machines/entitlements/adusers?enabled=true".format(api_url), params=params)

  if not response.status_code == 200:
      raise Exception(response.text)
  response_body = response.json()

  ad_users = response_body.get('data')

  pprint.pprint("Total Users: {}".format(response_body.get('total')))

  pprint.pprint(ad_users)

  if ad_users:
      user_guid = ad_users[0]['userGuid']
  else:
      raise Exception('No users!')

5.2 Add an entitlement

This is done through the /entitlements API and requires a Remote Workstation ID, userGuid, and deploymentId.

First we will list the Remote Workstations and extract the Remote Workstation ID and deployment ID from the response. Then we will use the response from /adusers above to assign the first user to the Remote Workstations.

  body = dict(
      deploymentId=deployment_id,
      machineId=machine_id,
      userGuid=user_guid,
  )

  response = session.post("{}/machines/entitlements".format(api_url),
  json=body)

  if not response.status_code == 201:
      raise Exception(response.text)
  response_body = response.json()

  entitlement = response_body.get('data')

  pprint.pprint(entitlement)

An Anyware Manager Service Account can be used to create a deployment and a Deployment service account for the deployment.

6.1 Signing in with an Anyware Manager Service Account

If you have an Anyware Manager Service Account or a Deployment Service Account you can use the function below to sign in and get a token.

  def signin_with_service_account(account):
      # sign in using the account
      resp = requests.post(
          '{}/auth/signin'.format(api_url),
          json=account,
          verify=True,
      ).json()

      token = resp.get('data').get('token')
      return token

6.2 Creating a deployment and a Deployment Service Account

The code below uses an Anyware Manager Service Account to create a deployment

  # this is the Anyware Manager service account that can be downloaded Anyware Manager Admin Console
  awm_service_account = {
    "keyId": "key-id",
    "username": "the-username",
    "apiKey": "the secret",
    "keyName": "awm-service-account-1"
  }

  token = signin_with_service_account(awm_service_account)

  # now, you use the token to create a deployment
  deployment = {
      'deploymentName' : 'my new deployment',
      'registrationCode': 'your-registration-code',
  }

  resp = requests.post(
      '{}/deployments'.format(api_url),
      headers=dict(authorization=token),
      verify=True,
      json=deployment
  ).json()

Now it uses the deployment ID and the same token to create a Deployment Service Account for the deployment.

  deployment_id = resp.get('data').get('deploymentId')

  resp = requests.post(
      '{}/auth/keys'.format(api_url),
      json={'deploymentId': deployment_id},
      verify=True,
      headers=dict(authorization=token),
  ).json()

  # get the Deployment Service Account from this response
  # YOU MUST SAVE IT, AS IT IS ONLY RETURNED NOW!
  deployment_service_account = resp.get('data')

6.3 Using the Deployment Service Account on your deployment

After having your Deployment Service Account you can use it to sign in and get a token.

  deployment_token = signin_with_service_account(deployment_service_account)

  Using this token you can now interact with your deployment.

  The code below uses the deployment token to change the deployment name.

  resp = requests.put(
      '{}/deployments/{}'.format(api_url, deployment_id),
      json={ 'deploymentName': 'my deployment renamed' },
      verify=True,
      headers=dict(authorization=deployment_token),
  ).json()

Now that you have an entitled workstation running a PCoIP agent, you can connect to it and establish a session using a PCoIP client. The connection will be brokered by the connector you configured above.

6.1 Download a software client

If you do not already have a PCoIP software client or zero client, you can download a software client from Teradici here.

6.2 Connect to the remote workstation

In the client, enter the FQDN or IP address of the connector you set up above: Enter the credentials for the user you entitled, then select the machine and connect.

Programmatic access to perform operations on Anyware Manager resources

At this time these keys have two scopes, create:deployment_tenant and create:keys:tenant. This allows them to create a deployment and at most one Deployment Key for each deployment it creates. This key can then be used to create more Deployment Keys and interact with the deployment and the resources under that deployment.

Programmatic Access to perform operations on Anyware Manager resources within a deployment

Validate and revoke tokens

Manage Provider Service Accounts

Sign in to Anyware Manager service

Manage users

Manage SAML configuration

Manage Users allowed to login via the identity provider from the SAML configuration.

Manage User Groups allowed to login via the identity provider from the SAML configuration.

Manage Deployments