Cloud Support API V2 User Guide

Overview

To learn more about why you'd want to use the Cloud Support API and what it's for, see Cloud Support API overview. This page teaches you how to get started with version 2 of the Cloud Support API. There's also a v2beta version available, but there are few differences between the two. Some changes and features may be available in v2beta before v2, but the v2 API is probably a better fit for most use cases.

Now we'll discuss how to set up the v2 API.

Getting Started

Before you can use the Cloud Support API, do the following:

  1. Enable the Cloud Support API by visiting the Cloud Support API page in Google Cloud console and clicking ENABLE.

  2. Provision a service account by following the instructions at Create service accounts. To learn more about service accounts, see Service accounts overview.

  3. Use the IAM tab in Google Cloud console to grant the service account the Organization Viewer role or some other role that grants the resourcemanager.organizations.get permission.

    You can also use the gcloud organizations add-iam-policy-binding command:

    gcloud organizations add-iam-policy-binding \\
organizations/ORG_ID \\
--role roles/resourcemanager.organizationViewer \\
--member SERVICE_ACCOUNT

    To learn how to find the correct value for 'ORG_ID', see Retrieve your organization ID.

  4. Grant the service account the Tech Support Editor or Tech Support Viewer role. To do that, run:

    gcloud organizations add-iam-policy-binding \\
organizations/ORG_ID \\
--role roles/cloudsupport.techSupportEditor \\
--member SERVICE_ACCOUNT

  5. If you're using third-party integrations like JIRA, give the third-party application access to the service account. To learn more about authentication, see Authentication overview.

If you want to use OAuth 2.0 for authentication:

  1. If you aren't already using OAuth2 to authenticate with Google, set it up by following OAuth 2.0 to Access Google APIs. Pay extra attention to the section about incremental authorization.

  2. Make sure the following two scopes are added to the OAuth2 client IDs used by your application:

    • For general access to Google Cloud: https://www.googleapis.com/auth/cloud-platform or https://www.googleapis.com/auth/cloud-platform.read-only
    • For access to retrieve or create support cases and other support related data: https://www.googleapis.com/auth/cloudsupport

Access Control and IAM Roles

Customer Care uses the following IAM Roles to control access to cases. You can use these or you can make your own custom roles with whatever permissions you'd like. To learn more about IAM, see Access control with IAM.

Role Permissions
Tech Support Viewer cloudsupport.techCases.get
cloudsupport.techCases.list
cloudsupport.techCaseAttachments.list
cloudsupport.techCaseAttachments.download
cloudsupport.techCaseComments.list
cloudsupport.techCaseUpdates.list
Tech Support Editor Tech Support Viewer permissions
cloudsupport.techCases.create
cloudsupport.techCases.update
cloudsupport.techCases.escalate
cloudsupport.techCases.close
cloudsupport.techCaseAttachments.create
cloudsupport.techCaseComments.create

Deciding which libraries to use to call the Cloud Support API

There are three general paths to call the API.

  1. Use the Cloud Support API Cloud Client Libraries for the language you want to use. These are available for a wide variety of languages, but they don't support uploading or downloading attachments. To learn more about this type of library, see Cloud Client Libraries

  2. Use the Python Google API Library to build a stub to call the Cloud Support API. This is the legacy approach to calling the API. You can upload or download attachments with it. To learn more about this type of library, see Google API Client Libraries.

  3. Use cURL or otherwise directly call the API. This has the advantage of being completely customizable, but requires you to configure everything yourself.

If you don't need to use attachments, we recommend using Cloud Client Libraries. Otherwise, we recommend using the Python Google API Library.

Using Cloud Client Libraries

The Cloud Support API has Cloud Client Libraries available for:

To get started with one, just go to its page and follow the directions there.

Using the Python Google API library

To get started with the Python Google API library, do the following:

  1. Install the google discovery package with pip.

    pip install google-api-python-client

  2. Build a stub in your code.

    import googleapiclient.discovery

api_version = "v2"
supportApiService = googleapiclient.discovery.build(
    serviceName="cloudsupport",
    version=api_version,
    discoveryServiceUrl=f"https://cloudsupport.googleapis.com/$discovery/rest?version={api_version}",
)

  3. Call the endpoint you're interested in. We've provided examples of doing that for each endpoint in the Cloud Support API. For example, see cases.list.

When you make calls to the API with the Python Google API library, it will use the default credentials for the environment your program is running in. Make sure that the service account in that environment has the permissions mentioned in the Getting Started section.

Using cURL

There are two main ways to authenticate your cURL call. You can use a service account, or you can use application default credentials. To learn more about application default credentials, see How Application Default Credentials works.

Authenticating with a Service Account

  1. Authenticate using Google Cloud CLI.

    gcloud auth activate-service-account SERVICE_ACCOUNT_EMAIL \
  --key-file=/path/key.json \
  --project=PROJECT_ID

  2. Send the request.

    curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  https://cloudsupport.googleapis.com/v2/organizations/ORGANIZATION_ID/cases

Authenticating with Application Default Credentials

  1. Authenticate using Google Cloud CLI.

    gcloud auth application-default login

  2. Send the request. Be sure to include an x-goog-user-project header, which is required when you call the Cloud Support API with application default credentials.

    curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "x-goog-user-project: $(gcloud config get-value project)" \
  https://cloudsupport.googleapis.com/v2/organizations/ORGANIZATION_ID/cases