Stay organized with collections Save and categorize content based on your preferences.

Authorizing API requests

The BigQuery API uses OAuth 2.0 access tokens or JSON Web Tokens (JWTs) to authorize requests. These tokens grant temporary access to an API.

When possible, you should use Application Default Credentials (ADC) in your application to discover credentials from well-known sources, including OAuth 2.0 and JWTs. For more information, see Finding credentials automatically.

If you can't use ADC, you can use Google's OAuth 2.0 server to obtain an OAuth 2.0 access token or, if you are using a service account for authentication, then you can use a signed JWT instead. Using a JWT lets you avoid making a network request to Google's authorization server before making an API call.

Before you begin

Authenticate with OAuth 2.0

This section shows you how to supply an OAuth 2.0 access token to the BigQuery API. If you use the BigQuery client libraries, you do not need this information, as this is done for you automatically.

Scopes

Access tokens are associated with a scope, which limits the token's access. Check the complete list of Google API scopes for scopes that are associated with the BigQuery API.

Get access tokens

Get a temporary access token using Application default credentials.

Command-line

Use the Google Cloud CLI to print an access token. 

ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"

See the authentication guide to learn how to get an access token in other environments.

Because access tokens provide only temporary authorization, you must periodically refresh them.

Authorize requests

To authorize requests to the BigQuery API with an access token, use any of the OAuth 2.0 token usage methods.

Request header

Set the token in the Authorization request header with the value Bearer ACCESS_TOKEN.

Command-line

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://www.googleapis.com/bigquery/v2/projects/$GOOGLE_CLOUD_PROJECT/datasets"

Authenticate with JWTs

You can use JWTs to authenticate in the following ways:

Audience

For JWTs, an audience claim is used instead of a scope. For the BigQuery APIs, set the audience value to https://bigquery.googleapis.com/.

Create JWTs with client libraries

For service account keys created in Google Cloud console or by using the gcloud CLI, use a client library that provides JWT signing. The following list provides some appropriate options for popular programming languages:

Java example

The following example uses the BigQuery client library for Java to create and sign a JWT.

import com.google.auth.Credentials;
import com.google.auth.oauth2.ServiceAccountJwtAccessCredentials;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;

import java.io.FileInputStream;
import java.net.URI;

public class Example {
    public static void main(String... args) throws Exception {
        String projectId = "myproject";
        // Load JSON file that contains service account keys and create ServiceAccountJwtAccessCredentials object.
        String credentialsPath = "/path/to/key.json";
        URI audience = URI.create("https://bigquery.googleapis.com/");
        Credentials credentials = null;
        try (FileInputStream is = new FileInputStream(credentialsPath)) {
            credentials = ServiceAccountJwtAccessCredentials.fromStream(is, audience);
        }
        // Instantiate BigQuery client with the credentials object.
        BigQuery bigquery =
                BigQueryOptions.newBuilder().setCredentials(credentials).build().getService();
        // Use the client to list BigQuery datasets.
        System.out.println("Datasets:");
        bigquery
            .listDatasets(projectId)
            .iterateAll()
            .forEach(dataset -> System.out.printf("%s%n", dataset.getDatasetId().getDataset()));
    }
}

Create JWTs with REST or the gcloud CLI

For system-managed service accounts, you must manually assemble the JWT, then use the REST method projects.serviceAccounts.signJwt or the Google Cloud CLI command gcloud beta iam service-accounts sign-jwt to sign the JWT. To use either of these approaches, you must be a member of the Service Account Token Creator Identity and Access Management role.

gcloud CLI example

The following example shows a bash script that assembles a JWT and then uses the gcloud beta iam service-accounts sign-jwt command to sign it.

#!/bin/bash

SA_EMAIL_ADDRESS="myserviceaccount@myproject.iam.gserviceaccount.com"

TMP_DIR=$(mktemp -d /tmp/sa_signed_jwt.XXXXX)
trap "rm -rf ${TMP_DIR}" EXIT
JWT_FILE="${TMP_DIR}/jwt-claim-set.json"
SIGNED_JWT_FILE="${TMP_DIR}/output.jwt"

IAT=$(date '+%s')
EXP=$((IAT+3600))

cat <<EOF > $JWT_FILE
{
  "aud": "https://bigquery.googleapis.com/",
  "iat": $IAT,
  "exp": $EXP,
  "iss": "$SA_EMAIL_ADDRESS",
  "sub": "$SA_EMAIL_ADDRESS"
}
EOF

gcloud beta iam service-accounts sign-jwt --iam-account $SA_EMAIL_ADDRESS $JWT_FILE $SIGNED_JWT_FILE

echo "Datasets:"
curl -L -H "Authorization: Bearer $(cat $SIGNED_JWT_FILE)" \
-X GET \
"https://bigquery.googleapis.com/bigquery/v2/projects/myproject/datasets?alt=json"

What's next