Authenticate with JWTs

The BigQuery API acceptsJSON Web Tokens (JWTs) toauthenticate requests.

As a best practice, you should useApplication Default Credentials (ADC) to authenticate to BigQuery.If you can't use ADC and you're using a service account for authentication, thenyou canuse a signed JWTinstead. JWTs let you make an API call without a network request to Google'sauthorization server.

You can use JWTs to authenticate in the following ways:

Scope and Audience

Usescopes with service account when possible. If not possible, you can use anaudience claim.For the BigQuery APIs, set the audience value tohttps://bigquery.googleapis.com/.

Create JWTs with client libraries

For service account keys created in Google Cloud console or by using thegcloud CLI, use a client library that provides JWTsigning. The following list provides some appropriate options for popularprogramming languages:

Java example

The following example uses theBigQuery client library for Javato create and sign a JWT. The default scope for BigQuery API is set tohttps://www.googleapis.com/auth/bigquery in the client library.

importcom.google.auth.oauth2.ServiceAccountCredentials;importcom.google.cloud.bigquery.BigQuery;importcom.google.cloud.bigquery.BigQueryOptions;importcom.google.common.collect.ImmutableList;importjava.io.FileInputStream;importjava.io.IOException;importjava.net.URI;publicclassExample{publicstaticvoidmain(String...args)throwsIOException{StringprojectId="myproject";// Load JSON file that contains service account keys and create ServiceAccountCredentials object.StringcredentialsPath="/path/to/key.json";ServiceAccountCredentialscredentials=null;try(FileInputStreamis=newFileInputStream(credentialsPath)){credentials=ServiceAccountCredentials.fromStream(is);// The default scope for BigQuery is used.// Alternatively, use `.setScopes()` to set custom scopes.credentials=credentials.toBuilder().setUseJwtAccessWithScope(true).build();}// Instantiate BigQuery client with the credentials object.BigQuerybigquery=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, thenuse the REST methodprojects.serviceAccounts.signJwtor the Google Cloud CLI commandgcloud beta iam service-accounts sign-jwtto sign the JWT. To use either of these approaches, you must be a member of theService Account Token CreatorIdentity and Access Management role.

gcloud CLI example

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

#!/bin/bashSA_EMAIL_ADDRESS="myserviceaccount@myproject.iam.gserviceaccount.com"TMP_DIR=$(mktemp-d/tmp/sa_signed_jwt.XXXXX)trap"rm -rf${TMP_DIR}"EXITJWT_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"}EOFgcloudbetaiamservice-accountssign-jwt--iam-account$SA_EMAIL_ADDRESS$JWT_FILE$SIGNED_JWT_FILEecho"Datasets:"curl-L-H"Authorization: Bearer$(cat$SIGNED_JWT_FILE)"\-XGET\"https://bigquery.googleapis.com/bigquery/v2/projects/myproject/datasets?alt=json"

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.