Skip to main content

Set Up External API Access

Cloudaware External APIs allow authorized external clients to perform supported operations in Cloudaware, such as managing cloud accounts or working with TunHub tunnels.

This guide explains how to configure external API access. During this guide, you will generate:

  • A long-lived Cloudaware OAuth token.
  • A Google Cloud API key for the approved project.

Prerequisites​

Before you begin, make sure you have:

  • Administrator access to Cloudaware.
  • A Google Cloud account. A free trial account can be used.
  • A Google Cloud project approved by Cloudaware Support for access to the Cloudaware External API.

High-Level Flow​

To set up access to Cloudaware External APIs:

  1. Generate an OAuth token in Cloudaware.
  2. Ask Cloudaware Support to grant your Google Cloud project access to the private Cloudaware External API.
  3. Enable the API in the approved Google Cloud project.
  4. Generate an API key restricted to the Cloudaware External API.
  5. Add the API key to Google APIs Explorer.
  6. Select an External API method and authenticate the request using the Cloudaware OAuth token.

Get an OAuth Token​

Cloudaware uses OAuth to authenticate requests to the Cloudaware API. To get an OAuth token:

  1. Log in to Cloudaware → Admin.

  2. In the left menu, select API CREDENTIALS. Under OAuth Tokens, click +CREATE TOKEN → CREATE TOKEN.

    note

    You might be redirected to a Force.com page to grant access to Cloudaware OAuth 2.0. Click Allow to continue.

  3. Click Copy To Clipboard to copy the token, and store it securely.

  4. Click GOT IT, CLOSE WINDOW to proceed.

    tip

    If your environment has IP restrictions, update the OAuth policy settings:

    • In Cloudaware, go to Setup.
    • Search for Apps in the search bar. Under Connected Apps, select Manage Connected Apps and click the Cloudaware OAuth2 app.
    • Click Edit Policies.
    • In the IP Relaxation field, select Relax IP restrictions.
    • Click Save.

You can create additional tokens or revoke existing tokens here, in Cloudaware Admin → API CREDENTIALS:

  • To revoke a token, in the three-dot menu select Revoke → Yes, Revoke.
  • To generate another token, click +CREATE TOKEN.
warning

You can have 4 active tokens at a time. The Use Count column shows how many times each token has been used.

Get a Google Cloud API Key​

A Google Cloud API key is required to send requests to the private Cloudaware External API.

  1. Create a Google Cloud account.
  2. Create a Google Cloud project.
  3. Submit an access request to Cloudaware Support at support@cloudaware.com. Include the full email address associated with the Google Cloud account that owns or manages the project.
  4. Before proceeding with the next step, wait for Cloudaware Support to confirm that API access has been granted.
  5. Activate API access:
    • Go to Google Cloud Console and select the approved project.
    • Open the navigation menu → APIs & Services → Library.
    • Filter the available APIs by Private.
  6. Select external.endpoints.cloudaware-vm.cloud.goog → Enable.
  7. Go back to APIs & Services → Credentials → Create Credentials → API Key.
  8. In the API restrictions dropdown, select the external.endpoints.cloudaware-vm.cloud.goog API. Click Create.
  9. Copy the API key to your clipboard.

Add the API key to Google APIs Explorer​

Google APIs Explorer lets you review available operations, enter request parameters, and test API requests.

  1. Open Google APIs Explorer.
  2. Click the gear icon → Set API key / OAuth 2.0 Client ID.
  3. Paste the API key, leave OAuth 2.0 Client ID blank, and click Save.

Common Use Cases​

After configuring the OAuth token, Google Cloud API key, and Google APIs Explorer, use the appropriate External API operation for your workflow.

Add Cloud Accounts​

Use Cloudaware External APIs to add and manage cloud accounts without onboarding them manually through the Cloudaware UI.

Cloudaware provides operations for AWS accounts, Microsoft Entra ID tenants, Azure applications, and Azure subscriptions. The following example adds an AWS account.

Before proceeding, collect the following information:

  • The ARN of the IAM role created in the AWS account.
  • An external ID (optional).
  • A display name for the account.
  • The AWS partition.

Steps:

  1. In Google APIs Explorer, go to Services → External API v1.

  2. Select external.amazon.accounts.create.

  3. Fill out the form.

    FieldValue
    tokenPaste the OAuth token generated earlier.
    sandboxSelect true if your Cloudaware Salesforce organization is a sandbox. Otherwise, select false.
    fieldsClick Use fields editor, and then select all to include all fields in the response.
    Request bodySpecify the role, name, and usages properties.

    Sample request body without values:

    {
      "role": {
        "externalId": "<external_id>",
        "roleArn": "arn:aws:iam::<account_id>:role/<role_name>",
        "trustedAccount": {
          "accountId": "<trusted_account_id>",
          "partition": "<partition>"
        }
      },
      "name": "<account_name>",
      "usages": []
    }

    Where:

    • role.externalId: External ID for the Cloudaware Collector. Leave unset if you haven’t generated one in Cloudaware Admin UI.
    • role.roleArn: Full ARN of the IAM role you create in the AWS account being onboarded. Format: arn:aws:iam::<account_id>:role/<role_name>.
    • role.trustedAccount.accountId: The Cloudaware account ID used for role assumption. The account ID is 814021343637 for the aws partition and 321683528484 for the aws-us-gov partition. You can verify the account ID in the Mappings section of the Cloudaware CloudFormation template.
    • role.trustedAccount.partition: Almost always "aws" for standard commercial AWS accounts. Only changes to "aws-cn" if an account lives in AWS China, or "aws-us-gov" if it's in GovCloud.
    • name: A display name for this account as it will show up in Cloudaware, for example, Prod - US-East.
    • usages: Specifies the basic ("COLLECTOR") and add-on ("MONITORING", "ELM", and "CONFLUX") functionality to enable for the AWS account added to Cloudaware. If left blank, "COLLECTOR" is set by default.

  4. Click Authorize and Execute.

  5. Review the response to confirm that the account was added successfully.

Use the corresponding create, list, update, or remove operation to manage other supported cloud-account connections. See the List of External APIs below.

Check Status of TunHub Tunnels​

Use the external.tunhub.tunnels.getAll operation to retrieve TunHub tunnels available in the Cloudaware environment and review their current status.

Before proceeding, make sure that TunHub is configured for your Cloudaware account.

Steps:

  1. In Google APIs Explorer, go to Services → External API v1.

  2. Select external.tunhub.tunnels.getAll.

  3. Fill out the form.

    FieldValue
    tokenPaste the OAuth token generated earlier.
    sandboxSelect true if your Cloudaware Salesforce organization is a sandbox. Otherwise, select false.
    fieldsClick Use fields editor, and then select all to include all fields in the response. Click + to expand the list of items, and clear any fields you do not need.

  4. Click Authorize and Execute.

  5. Review the returned tunnel records and their status information.

Use the response to identify tunnels that are available, inactive, or require investigation. The exact fields returned depend on the current External API response schema.

List of External APIs​

The following External API operations are available:

AWS Accounts

  • external.amazon.accounts.create
  • external.amazon.accounts.list
  • external.amazon.accounts.remove
  • external.amazon.accounts.update

Applications

  • external.applications.batch.upsert
  • external.applications.list
  • external.applications.remove
  • external.applications.tiers.remove

Azure Active Directories

  • external.azure.activeDirectories.create
  • external.azure.activeDirectories.list
  • external.azure.activeDirectories.remove
  • external.azure.activeDirectories.update

Azure Applications

  • external.azure.applications.list
  • external.azure.applications.remove
  • external.azure.applications.update

Azure Subscriptions

  • external.azure.subscriptions.create
  • external.azure.subscriptions.list
  • external.azure.subscriptions.remove
  • external.azure.subscriptions.update

Compliance

  • external.compliance.policies.executeTests
  • external.compliance.policies.generate
  • external.compliance.schema.list
  • external.compliance.types.filter
  • external.compliance.types.get
  • external.compliance.types.list

Incidents

  • external.incidents.create

New Relic Accounts

  • external.newRelic.accounts.create
  • external.newRelic.accounts.getAll
  • external.newRelic.accounts.remove
  • external.newRelic.accounts.rotateApiKey
  • external.newRelic.accounts.update

Sessions

  • external.session.create

TunHub

  • external.tunhub.tunnels.getAll
On this page