Authenticate with REST

This page describes how to authenticate when you make a REST request to a Google API.

For information about how to authenticate when you use Google client libraries, see Authenticate using client libraries.

Before you begin

To run the samples on this page, complete the following steps:

  1. Install the Google Cloud CLI.

  2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  3. To initialize the gcloud CLI, run the following command: 

    gcloud init

  4. Enable the Cloud Resource Manager and Identity and Access Management (IAM) APIs:

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles. 

    gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

If you don't want to use the gcloud CLI, you can skip these steps and use service account impersonation or the metadata server to generate a token.

Types of credentials

You can use the following types of credentials to authenticate a REST call:

  • Your gcloud CLI credentials.

    This approach is the easiest and most secure way to provide credentials to a REST method in a local development environment. If your user account has the necessary Identity and Access Management (IAM) permissions for the method you want to call, this is the preferred approach.

    Your gcloud credentials are not the same as the credentials you provide to ADC using the gcloud CLI. For more information, see gcloud CLI authentication configuration and ADC configuration.

  • The credentials provided to Application Default Credentials (ADC).

    This method is the preferred option for authenticating a REST call in a production environment, because ADC finds credentials from the resource where your code is running (such as a Compute Engine virtual machine). You can also use ADC to authenticate in a local development environment. In this scenario, the gcloud CLI creates a file that contains your credentials in your local file system.

  • The credentials provided by impersonating a service account.

    This method requires more setup. If you want to use your existing credentials to obtain short-lived credentials for another service account, such as testing with a service account locally or requesting temporary elevated privileges, use this approach.

  • The credentials returned by the metadata server.

    This method works only in environments with access to a metadata server. The credentials returned by the metadata server are the same as the credentials that would be found by Application Default Credentials using the attached service account, but you explicitly request the access token from the metadata server and then provide it with the REST request. Querying the metadata server for credentials requires an HTTP GET request; this method does not rely on the Google Cloud CLI.

  • API keys

    You can use an API key with a REST request only for APIs that accepts API keys. In addition, the API key must not be restricted to prevent it from being used with the API.

gcloud CLI credentials

To run the following example, you need the resourcemanager.projects.get permission on the project. The resourcemanager.projects.get permission is included in a variety of roles—for example, the Browser role (roles/browser).

  1. Use the gcloud auth print-access-token command to insert an access token generated from your user credentials.

    The following example gets details for the specified project. You can use the same pattern for any REST request.

    Before using any of the request data, make the following replacements:

    • PROJECT_ID: Your Google Cloud project ID or name.

    To send your request, choose one of these options:

    curl

    Execute the following command: 

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

    PowerShell

    Execute the following command: 

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

    The details for your project are returned.

For APIs that require a quota project, you must set one explicitly for the request. For more information, see Set the quota project with a REST request on this page.

Application Default Credentials

To run the following example, the principal associated with the credentials you provide to ADC needs the resourcemanager.projects.get permission on the project. The resourcemanager.projects.get permission is included in a variety of roles—for example, the Browser role (roles/browser).

  1. Provide credentials to ADC.

    If you are running on a Google Cloud compute resource, you shouldn't provide your user credentials to ADC. Instead, use the attached service account to provide credentials. For more information, see Set up ADC for a resource with an attached service account.

  2. Use the gcloud auth application-default print-access-token command to insert the access token returned by ADC into your REST request.

    The following example gets details for the specified project. You can use the same pattern for any REST request.

    Before using any of the request data, make the following replacements:

    • PROJECT_ID: Your Google Cloud project ID or name.

    To send your request, choose one of these options:

    curl

    Execute the following command: 

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
         "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

    PowerShell

    Execute the following command: 

    $cred = gcloud auth application-default print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

    The details for your project are returned.

    If your request returns an error message about end-user credentials not being supported by this API, see Set the quota project with a REST request on this page.

Impersonated service account

The simplest way to impersonate a service account to generate an access token is by using the gcloud CLI. However, if you need to generate the token programmatically, or you don't want to use the gcloud CLI, you can use impersonation to generate a short-lived token.

For more information about impersonating a service account, see Use service account impersonation.

  1. Review the required permissions.

    • The prinicipal you want to use to perform the impersonation must have the iam.serviceAccounts.getAccessToken permission on the impersonated service account (also called the privilege-bearing service account). The iam.serviceAccounts.getAccessToken permission is included in the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator). If you are using your user account, you need to add this permission even if you have the Owner role (