The Data Studio API lets you search for and manage Data Studio assets. The primary use case for the API is to allow Google Workspace or Cloud Identity organizations to automate management and migration of Data Studio assets. > [!IMPORTANT] > **Key Point:** The API is only available to users that belong to an organization with Google Workspace or Cloud Identity. ## Requirements overview Follow these steps to use the Data Studio API: 1. [Configure an app to use the API](https://developers.google.com/data-studio/integrate/api#configure-app). 2. [Use the Google Admin console to authorize the app](https://developers.google.com/data-studio/integrate/api#authorize-app). 3. [Obtain OAuth 2.0 access tokens and call the API](https://developers.google.com/data-studio/integrate/api#calling-api). 4. [List assets and get metadata](https://developers.google.com/data-studio/integrate/api#list-assets). The preceding steps may be performed by the same or different organizations based on the following common scenarios: **Internal apps** that are developed for an organization. The organization configures and authorizes the app for all users of its organization. \* **Third-party apps** that are developed for external users or customers (for example, developers and users would belong to different organizations). The developer configures the app, but the user's organization authorizes the third-party app. ## 1. Configure an app to use the API Complete the following to configure your app: - [Enable the API](https://developers.google.com/data-studio/integrate/api#enable_the_api) - [Create an OAuth client](https://developers.google.com/data-studio/integrate/api#create_an_oauth_client) #### Enable the API To enable an API for your project: 1. Open the \[Data Studio API\] in the Google API Console. 2. If prompted, select a project, or create a new one. 3. Click **Enable**. 4. If prompted, read and accept the API's Terms of Service. #### Create an OAuth Client The following steps to create an OAuth Client are general guidelines and should be adjusted to meet your app requirements. > [!IMPORTANT] > **Important:** Don't add Data Studio scopes to your OAuth Client. The scopes will be added by the Workspace admin when they authorize the app. 1. Navigate to [Configure OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent). 1. Choose **Internal** , click **Create**. 2. Fill out required fields, click **Save**. 2. Navigate to [Credentials](https://console.cloud.google.com/apis/credentials). 1. Click **CREATE CREDENTIALS**. 2. Select **OAuth client ID**. 3. Choose the appropriate `Application Type`. (Web application is most common). 4. Fill required fields, click **Create**. 3. Take note of the **Client ID** since it is used to authorize the app. ## 2. Authorize the app for an organization Apps using the Data Studio API can only authenticate and authorize Google Workspace users where the user's organization has authorized the app using [Domain-wide delegation to control API access](https://support.google.com/a/answer/162106). Configure *domain-wide delegation* with the OAuth **Client ID** of the app and the **Scopes** required by the app. > [!IMPORTANT] > **Important:** The following steps must be completed by a Workspace admin. The admin will need the **OAuth Client ID** of the app and a list of **OAuth Scopes** required by the app. 1. Sign in to your Google Admin console and navigate to [domain wide delegation](https://admin.google.com/ac/owl/domainwidedelegation). 2. In `API clients`, click **Add new**. 3. Enter the `Client ID` of the app to authorize (i.e. the app that uses the Data Studio API). 4. Enter **all** OAuth scopes required by the app. The following scopes are commonly requested if using the Data Studio API to manage assets: - `https://www.googleapis.com/auth/datastudio` - `https://www.googleapis.com/auth/userinfo.profile` 5. Click **Authorize**. > [!NOTE] > **Note:** If your app doesn't need to manage Data Studio assets, consider using the more restrictive `https://www.googleapis.com/auth/datastudio.readonly` scope instead of `https://www.googleapis.com/auth/datastudio`. After authorizing the app, any Workspace user belonging to the organization will automatically be authorized to use the app with the Data Studio API. ## 3. Obtaining OAuth 2.0 access tokens and calling the API Once you have developed and authorized the app you will have the necessary access to call the API for Workspace users. See [Using OAuth 2.0 to Access Google APIs](https://developers.google.com/identity/protocols/OAuth2) for details on working with Google APIs using OAuth. Refer to the [API reference](https://developers.google.com/data-studio/integrate/api/reference) for available operations. ## 4. List assets and get metadata You can use the [`assets:search`](https://developers.google.com/data-studio/integrate/api/reference/assets/search) method to get a list of Data Studio assets and their metadata. For example, to get a list of all reports that are accessible to the authenticated user, use the following HTTP request: GET https://datastudio.googleapis.com/v1/assets:search?assetTypes=REPORT You can filter results by title or owner. For example, to search for reports that have "Sales" in the title and that are owned by `user@example.com`, use the following: GET https://datastudio.googleapis.com/v1/assets:search?assetTypes=REPORT&title=Sales&owner=user@example.com See [`assets:search`](https://developers.google.com/data-studio/integrate/api/reference/assets/search) documentation for advanced search options that use the `title` parameter, including filtering for assets owned by or created by authenticated user (`owner:me`, `creator:me`). A successful response will contain a list of [Asset](https://developers.google.com/data-studio/integrate/api/reference/types#Asset) objects. The following metadata is available for each asset: `name` (asset ID), `title`, `description`, `owner`, `creator`, `createTime`, `updateTime`, `assetType`, and `trashed`. You can view any report asset by using the following link: `https://datastudio.google.com/reporting/{asset.name}` > [!NOTE] > **Note:** Deeper metadata like filters, sections, and dimensions within a report cannot be retrieved using the API. ## Troubleshooting ### Missing OAuth dialog If a user's organization has [authorized the app](https://developers.google.com/data-studio/integrate/api#authorize-app), users of that organization will not be shown the OAuth dialog when authorizing the app. The only exception would be if the app requests authorization for additional Google API scopes that the Workspace Admin hasn't configured, in which case the OAuth dialog will be shown to users. ### Error 400: invalid_scope If a user receives an `Error 400: invalid_scope` message when attempting to authorize the app, then the user's organization has not or incorrectly [authorized the app](https://developers.google.com/data-studio/integrate/api#authorize-app). To resolve the issue, the user will have to request that their organization authorize the app. ![A OAuth 400 error message indicating an invalid scope was requested](https://developers.google.com/static/data-studio/integrate/api/images/scope_error.png "Error 400: invalid_scope")