Set up & authorize requests

Before you begin developing, you need to review the Chrome Policy API Terms of Service, create a Google Cloud project, enable the Chrome Policy API, and set up access credentials.

The Chrome Policy API respects admin role permissions and is governed by defined authorization scopes.

Step 1: Create a Google Cloud project

A Google Cloud project is required to use the Chrome Policy API. This project forms the basis for creating, enabling, and using all Google Cloud services, including managing APIs, enabling billing, adding and removing collaborators, and managing permissions.

If you don't already have a Google Cloud project you want to use, follow the steps below to create a Google Cloud project:

  1. Open the Google Cloud Console.
  2. At the top-left, click Menu > IAM & Admin > Create a Project.
  3. In the Project Name field, enter a descriptive name for your project.
  4. In the Location field, click Browse to display the organizations available for assignment. Choose the organization for which you want to manage Chrome policies, then click Select.
  5. Click Create. The console navigates to the Dashboard page and your project is created within a few minutes.

Step 2: Enable the Chrome Policy API

To enable the Chrome Policy API in your Google Cloud project:

  1. Open the Google Cloud Console.
  2. At the top, choose your Google Cloud project.
  3. At the top-left, click Menu > APIs & Services > Library.
  4. In the search field, enter "Chrome" and press Enter.
  5. In the list of search results, click Chrome Policy API.
  6. Click Enable.
  7. To enable more APIs, repeat steps 2–5.

Step 3: Create credentials

Requests to the Chrome Policy API can be authenticated as an end user or a robot service account.

  1. Open the Google Cloud Console.
  2. At the top, choose your Google Cloud project.
  3. At the top-left, click Menu > APIs & Services > OAuth consent screen.
  4. Select the user type for your app, then click Create.
  5. Complete the app registration form, then click Save and Continue.

  6. Click Add or remove scopes. A panel appears with a list of scopes for each API you've enabled in your Google Cloud project. Add one of the following authorization scopes:

    • https://www.googleapis.com/auth/chrome.management.policy
    • https://www.googleapis.com/auth/chrome.management.policy.readonly

    The readonly scope doesn't allow any mutation operations.

Set up end user or service account authentication

Click an option below for detailed instructions:

Option 1: Authenticate as an end user with OAuth 2.0

  1. Open the Google Cloud Console.
  2. At the top, choose your Google Cloud project.
  3. At the top-left, click Menu > APIs & Services > Credentials.
  4. Click Create Credentials > OAuth client ID.
  5. Follow the steps to create the OAuth 2.0 credentials.

No special setup is required in the Admin console by the organization's Chrome admin for OAuth 2.0 authentication. Users of your app will need to have the required admin role permissions associated with their account and need to agree to the app's OAuth consent screen.

Tip: You can test your app in the OAuth Playground.

Option 2: Authenticate as a service account

A service account is a special kind of account used by an application, rather than a person. You can use a service account to access data or perform actions by the robot account itself, or to access data on behalf of users. For more details, refer to Understanding service accounts.

Create a service account & credentials

  1. Open the Google Cloud Console.
  2. At the top, choose your Google Cloud project.
  3. At the top-left, click Menu > APIs & Services > Credentials.
  4. Click Create Credentials > Service account.
  5. Enter service account name, then click Create and continue.
  6. Optional: Assign roles to your service account to grant access to your Google Cloud project's resources. For more details, refer to Granting, changing, and revoking access to resources.
  7. Click Continue.
  8. Optional: Enter users or groups that can manage and perform actions with this service account. For more details, refer to Managing service account impersonation.
  9. Click Done. After a few minutes, your new service account appears in the "Service Accounts" list. (You might need to refresh the page.)
  10. In the "Service Accounts" list, click the service account you created.
  11. Click Keys > Add keys > Create new key.
  12. Select JSON, then click Create.

    Your new public/private key pair is generated and downloaded to your machine as a new file. This file is the only copy of this key. For information about how to store your key securely, see Managing service account keys.

Authorize the service account in the Admin console

If you choose to authenticate requests as a service account, the organization's Chrome administrator needs to perform additional steps in the Admin console to complete the process.

The Chrome admin can either assign a role to the service account directly with the required admin role permissions, or the Chrome admin can set up domain-wide delegation so the service account can impersonate users with proper permissions and act on their behalf.

To set up domain-wide delegation for your service account, the Chrome admin needs to follow these steps in the Admin console:

  1. Open the Admin console.
  2. At the top-left, click Menu > Security > Access and data control > API controls.
  3. Click Manage Domain Wide Delegation.
  4. Click Add new.
  5. In the "Client ID" field, paste the client ID associated with your service account. Learn how to find your service account's client ID.
  6. In the "OAuth Scopes" field, enter a comma-delimited list of the scopes required by the service account application. This is the same set of scopes defined when configuring the OAuth consent screen.
  7. Click Authorize.

Step 4: Test your app in the OAuth Playground

  1. Open the Google Cloud Console.
  2. At the top, choose your Google Cloud project.
  3. At the top-left, click Menu > APIs & Services > Credentials.
  4. Click Create Credentials > OAuth client ID.
  5. Click Application type > Web application.
  6. In the "Name" field, type a name for the credential. This name is only shown in the Cloud Console.
  7. For the time of testing, add https://developers.google.com/oauthplayground to "Authorized redirect URIs." You can remove this redirect URI from your app when done testing, if needed.
  8. Click Create and copy the "client ID" and "client secret" to your clipboard.
  9. In a new tab, open the OAuth 2.0 Playground.
  10. At the top-right, click OAuth 2.0 configuration .
  11. Select Use your own OAuth credentials. Then, paste the "client ID" and "client secret" you copied in step 8 and click Close.
  12. At the left, follow the OAuth 2.0 Playground steps:
    • For "Step 1: Select & authorize APIs," add https://www.googleapis.com/auth/chrome.management.policy and any other needed API scopes, then click Authorize APIs.
    • For "Step 2: Exchange authorization code for tokens," you can optionally select Auto-refresh the token before it expires.
    • For "Step 3: Configure request to API," enter your Chrome Policy API request URI, modifying the "HTTP Method" and other settings, as needed. Example URL request: https://chromepolicy.googleapis.com/v1/customers/my_customer/policySchemas?filter=chrome.printers

Step 5: Verify your app is trusted

An organization's admin can mark apps as trusted or blocked in the Admin console. For more details, see Control which third-party & internal apps access Google Workspace data.