Authenticating to the API

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

This page explains how to authorize requests to the Cloud Healthcare API.

Obtaining a service account key file

You can create service accounts with roles specific to Cloud Healthcare API such as a Healthcare Dataset Administrator or a Healthcare FHIR Store Administrator. To view all the available Cloud Healthcare API roles, see Roles.

You must grant the appropriate IAM roles to a service account to allow that service account to access relevant API methods.

The following steps show how to create a service account with the Healthcare FHIR Store Administrator role and to download a key file for this service account.

Console

Create a service account:

  1. In the Google Cloud console, go to the Create service account page.

    Go to Create service account
  2. Select your project.
  3. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

    In the Service account description field, enter a description. For example, Service account for quickstart.

  4. Click Create and continue.
  5. To provide access to your project, grant the following role(s) to your service account: roles/healthcare.fhirStoreAdmin .

    In the Select a role list, select a role.

    For additional roles, click Add another role and add each additional role.

  6. Click Continue.
  7. Click Done to finish creating the service account.

    Do not close your browser window. You will use it in the next step.

Create a service account key:

  1. In the Google Cloud console, click the email address for the service account that you created.
  2. Click Keys.
  3. Click Add key, and then click Create new key.
  4. Click Create. A JSON key file is downloaded to your computer.
  5. Click Close.

gcloud

Set up authentication:

  1. Create the service account:

    gcloud iam service-accounts create NAME

    Replace NAME with a name for the service account.

  2. Grant roles to the service account. Run the following command once for each of the following IAM roles: roles/healthcare.fhirStoreAdmin :

    gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

    Replace the following:

    • SERVICE_ACCOUNT_NAME: the name of the service account
    • PROJECT_ID: the project ID where you created the service account
    • ROLE: the role to grant
  3. Generate the key file:

    gcloud iam service-accounts keys create FILE_NAME.json --iam-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Replace the following:

    • FILE_NAME: a name for the key file
    • SERVICE_ACCOUNT_NAME: the name of the service account
    • PROJECT_ID: the project ID where you created the service account

Providing credentials to your application

The Cloud Healthcare API can use language-specific Google client libraries to authenticate applications and make calls to Google Cloud. For example, using the Google API Client Library for Python, you can build a service object using your credentials and then make calls to it.

You can provide credentials automatically or manually. Automatically providing credentials is useful when testing and experimenting, but can make it hard to tell which credentials your application is using. As an alternative, provide the credentials manually.

Setting the environment variables

You can provide authentication credentials to your application code or commands by setting the environment variable GOOGLE_APPLICATION_CREDENTIALS to the file path of the JSON file that contains your service account key.

Note that, if you are running your application on Compute Engine, Google Kubernetes Engine (GKE), or App Engine, you only need to set the GOOGLE_APPLICATION_CREDENTIALS environment variable if you are using a service account other than the default service account that those services provide.

The following samples show how to set the GOOGLE_APPLICATION_CREDENTIALS environment variable:

curl

If you're using curl, run the following command. Replace PATH with the file path of the JSON file that contains your service account key, and FILE_NAME with the filename. This variable only applies to your current shell session, so if you open a new session, set the variable again.

export GOOGLE_APPLICATION_CREDENTIALS=PATH/FILE_NAME

For example:

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account.json"

PowerShell

If you're using Windows PowerShell, run the following command. Replace PATH with the file path of the JSON file that contains your service account key, and FILE_NAME with the filename. This variable only applies to your current shell session, so if you open a new session, set the variable again.

$env:GOOGLE_APPLICATION_CREDENTIALS="PATH/FILE_NAME"

For example:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service_account.json"

After you've set the GOOGLE_APPLICATION_CREDENTIALS environment variable, Application Default Credentials (ADC) can implicitly determine your credentials.

Finding credentials automatically

Google API client libraries use Application Default Credentials (ADC) to automatically find your application's credentials.

When your code uses a client library, the client library checks for your credentials in the following order:

  1. ADC checks if the environment variable GOOGLE_APPLICATION_CREDENTIALS is set. If the variable is set, ADC uses the service account file that the variable points to. Setting the environment variables describes how to set the environment variable.
  2. If the environment variable isn't set, ADC uses the default service account that Compute Engine, Google Kubernetes Engine (GKE), or App Engine provide, if your application is running on any of those services.

If ADC can't use either of the above credentials, an error occurs.

The following code sample shows the use of ADC. The sample doesn't explicitly specify the application credentials. However, ADC can implicitly find the credentials and store them in the auth variable as long as the GOOGLE_APPLICATION_CREDENTIALS environment variable is set, or as long as the application is running on Compute Engine, GKE, or App Engine.

Node.js

Uses the Node.js client library.

const google = require('@googleapis/healthcare');
const healthcare = google.healthcare({
  version: 'v1',
  auth: new google.auth.GoogleAuth({
    scopes: ['https://www.googleapis.com/auth/cloud-platform'],
  }),
});

const createDataset = async () => {
  // TODO(developer): uncomment these lines before running the sample
  // const cloudRegion = 'us-central1';
  // const projectId = 'adjective-noun-123';
  // const datasetId = 'my-dataset';
  const parent = `projects/${projectId}/locations/${cloudRegion}`;
  const request = {parent, datasetId};

  await healthcare.projects.locations.datasets.create(request);
  console.log(`Created dataset: ${datasetId}`);
};

createDataset();

Obtaining and providing service account credentials manually

You can create and obtain service account credentials manually, and then pass the credentials to your application in its code. See Passing credentials manually for more information.

Service account authorization using JSON Web Tokens (JWTs)

You can make authorized calls to the Cloud Healthcare API that do not use OAuth 2.0. To do this, use a signed JSON Web Token (JWT) directly as a bearer token, instead of an OAuth 2.0 access token. The Cloud Healthcare API does not require a specific token generation method. A collection of helper client libraries can be found on JWT.io. When you use a signed JWT, you can avoid having to make a network request to Google's authorization server before making an API call.

When using a JWT, specify https://healthcare.googleapis.com/ in the aud field.

To authorize calls to the Cloud Healthcare API using a JWT instead of an access token, complete the instructions in Addendum: Service account authorization without OAuth.

The JWT you create should resemble the following sample:

   {
     "alg": "RS256",
     "typ": "JWT",
     "kid": "PRIVATE_KEY_ID"
   }
   .
   {
     "iss": "SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com",
     "sub": "SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com",
     "aud": "https://healthcare.googleapis.com/",
     "iat": CURRENT_UNIX_TIME,
     "exp": EXPIRATION_TIME
   }
   

What's next