## 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](https://docs.cloud.google.com/support/docs/reference/support-api).
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](https://console.cloud.google.com/apis/library/cloudsupport.googleapis.com)
   in Google Cloud console and clicking **ENABLE**.

2. Provision a service account by following the instructions
   at [Create service accounts](https://docs.cloud.google.com/iam/docs/service-accounts-create).
   To learn more about service accounts, see [Service accounts overview](https://docs.cloud.google.com/iam/docs/service-account-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:

   ```bash
   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](https://docs.cloud.google.com/resource-manager/docs/creating-managing-organization#retrieving_your_organization_id).
4. Grant the service account the Tech Support Editor or Tech Support Viewer
   role. To do that, run:

   ```bash
   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](https://docs.cloud.google.com/docs/authentication).

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](https://developers.google.com/identity/protocols/OAuth2). Pay extra attention to the section about [incremental authorization](https://developers.google.com/identity/protocols/OAuth2WebServer#incrementalAuth).

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](https://docs.cloud.google.com/support/docs/access-control).

|---|---|
| **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](https://docs.cloud.google.com/apis/docs/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](https://developers.google.com/api-client-library).

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:

- [Java](https://github.com/googleapis/google-cloud-java/tree/main/java-cloudsupport)
- [Python](https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-support)
- [.NET](https://github.com/googleapis/google-cloud-dotnet/tree/main/apis/Google.Cloud.Support.V2)
- [Go](https://github.com/googleapis/google-cloud-go/tree/main/support)
- [Node](https://github.com/googleapis/google-cloud-node/tree/main/packages/google-cloud-support)
- [Ruby](https://github.com/googleapis/google-cloud-ruby/tree/main/google-cloud-support-v2)
- [PHP](https://github.com/googleapis/google-cloud-php/tree/main/Support)

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.

   ```bash
   pip install google-api-python-client
   ```
2. Build a stub in your code.

   ```python
   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](https://docs.cloud.google.com/support/docs/reference/rest/v2/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](https://docs.cloud.google.com/support/docs/reference/v2#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](https://docs.cloud.google.com/docs/authentication/application-default-credentials).

#### Authenticating with a Service Account

1. Authenticate using Google Cloud CLI.

   ```bash
   gcloud auth activate-service-account SERVICE_ACCOUNT_EMAIL \
     --key-file=/path/key.json \
     --project=PROJECT_ID
   ```
2. Send the request.

   ```bash
   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.

   ```bash
   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.

   ```bash
   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
   ```