Creating and managing consent stores

This page shows how to create and manage consent stores.

The Consent Management API is a tool for recording user consents, managing actions based on those consents, and maintaining associated documentation and records.

The organization using the Consent Management API is responsible for obtaining and maintaining the required consents necessary to permit the processing of any data through the Consent Management API.

The Consent Management API fulfills the role of a policy decision point. Policy enforcement must be implemented in the application or through a proxy. For more information, see Attribute-based access control.

Set up permissions

To use the features in this guide, you must have the roles/healthcare.consentStoreAdmin role. However, to perform additional useful operations with the Consent Management API, additional permissions might be required. See Access control for more details.

Creating a consent store

Consent stores are the top-level resources that contain all information related to the configuration and operation of the Consent Management API. Consent stores belong to a Cloud Healthcare API dataset, which is assigned to a region when it is created. This region is the geographic location in which your consent store operates.

Console

To create a consent store in the Cloud Console, complete the following steps:

1. In the Cloud Console, go to the Datasets page.

   Go to the Datasets page

2. Select the dataset where you want to create a consent store.

3. Click Create data store.

4. Select Consent as the data store type.

5. In the ID field, enter a name of your choice that's unique in your dataset. If the name is not unique, the store creation fails.

6. Click Next.

7. In Configure your Consent Store select one of the following options to determine when consents in your store expire:

   • No default expiration time - by default, consents do not expire.
   • Default expiration time - by default, consents expire after the number of days defined in the Expiration time field.

8. To allow new consent resources to be created using UPDATE, click Allow consent creation on update.

9. Click Next.

10. Click Add label to define optional key and value labels to organize your Google Cloud resources.

11. Click Create.

API

To create a consent store, use the projects.locations.datasets.consentStores.create method.

curl

To create a consent store, make a POST request and specify the following information in the request:

• The name and location of the parent dataset.
• A name for the consent store that's unique in the consent store's parent dataset. The name can be any Unicode string of 1 to 256 characters consisting of numbers, letters, underscores, dashes, and periods.
• An optional default time until consents created in this store expire. This duration must be at least 24 hours (86400 seconds) and must be in the format DURATIONs. For example, if DURATION is set to 86400, the duration is defined as 86400s.
• An optional flag that determines whether requests to patch a non-existent consent resource should create that resource. Defaults to FALSE.

The following sample shows a POST request using curl:

curl -X POST \
   -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
   -H "Content-Type: application/json; charset=utf-8" \
   --data "{
     'default_consent_ttl' : 'DEFAULT_CONSENT_EXPIRATION_DURATION'
   }" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/consentStores?consentStoreId=CONSENT_STORE_ID"

If the request is successful, the server returns a response similar to the following sample in JSON format:

{
  "name": "projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID",
  "defaultConsentTtl": "DEFAULT_CONSENT_EXPIRATION_DURATION"
}

PowerShell

To create a consent store, make a POST request and specify the following information in the request:

• The name and location of the parent dataset.
• A name for the consent store that's unique in the consent store's parent dataset. The name can be any Unicode string of 1 to 256 characters consisting of numbers, letters, underscores, dashes, and periods.
• An optional default time until consents created in this store expire. This duration must be at least 24 hours (86400 seconds) and must be in the format DURATIONs. For example, if DURATION is set to 86400, the duration is defined as 86400s.
• An optional flag that determines whether requests to patch a non-existent consent resource should create that resource. Defaults to FALSE.

The following sample shows a POST request using Windows PowerShell:

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

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body "{
      'default_consent_ttl' : 'DEFAULT_CONSENT_EXPIRATION_DURATION'
    }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/consentStores?consentStoreId=CONSENT_STORE_ID" | Select-Object -Expand Content

If the request is successful, the server returns a response similar to the following sample in JSON format:

{
  "name": "projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID",
  "defaultConsentTtl": "DEFAULT_CONSENT_EXPIRATION_DURATION"
}

Getting consent store details

The following samples show how to get details about a consent store.

Console

To view a consent store's details:

1. In the Cloud Console, go to the Datasets page.

   Go to the Datasets page

2. Select the dataset containing the consent store you want to view.
3. Click the name of the consent store.

API

To get details about a consent store, use the projects.locations.datasets.consentStores.get method.

curl

To get details about a consent store, make a GET request and specify the following information:

• The name and location of the parent dataset
• The name of the consent store

The following sample shows a GET request using curl.

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID"

If the request is successful, the server returns the response in JSON format:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID"
}

If you configured any fields in the consentStore resource, they also appear in the response.

PowerShell

To get details about a consent store, make a GET request and specify the following information:

• The name and location of the parent dataset
• The name of the consent store

The following sample shows a GET request using Windows PowerShell.

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

Invoke-WebRequest `
  -Method Get `
  -Headers $headers `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID" | Select-Object -Expand Content

If the request is successful, the server returns the response in JSON format:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID"
}

If you configured any fields in the consentStore resource, they also appear in the response.

Listing the consent stores in a dataset

The following samples show how to list the consent stores in a dataset.

Console

To view the data stores in a dataset:

1. In the Cloud Console, go to the Datasets page.

   Go to the Datasets page

2. Click the ID of the dataset whose data stores you want to view.

API

To list the consent stores in a dataset, use the projects.locations.datasets.consentStores.list method.

curl

To list the consent stores in a dataset, make a GET request and specify the following information:

• The name of the parent dataset
• An optional search filter to retrieve consent stores with specific labels

The following sample shows a GET request using curl.

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores"

If the request is successful, the server returns the response in JSON format:

{
  "consentStores": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID"
    },
    {
      ...
    }
  ]
}

If you configured any fields in the consentStore resource, they also appear in the response.

PowerShell

To list the consent stores in a dataset, make a GET request and specify the following information:

• The name of the parent dataset
• An optional search filter to retrieve consent stores with specific labels

The following sample shows a GET request using Windows PowerShell.

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

Invoke-WebRequest `
  -Method Get `
  -Headers $headers `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores" | Select-Object -Expand Content

If the request is successful, the server returns the response in JSON format:

{
  "consentStores": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID"
    },
    {
      ...
    }
  ]
}

If you configured any fields in the consentStore resource, they also appear in the response.

Editing a consent store

After you create a consent store, you can update the default expiry duration and the labels.

The following samples show how to edit a consent store.

Console

To edit a consent store, complete the following steps:

1. In the Cloud Console, go to the Datasets page.

   Go to the Datasets page

2. Select the dataset containing the consent store you want to edit.
3. In the Data stores list, click the data store you want to edit.
4. To edit the consent store's configuration, click the edit icon next to Consent Store Configuration.
   
   For more information on the consent store's configuration options, see Creating a consent store.
5. To add one or more labels to the store, click the edit icon next to Labels, click Add label, and enter the key/value label. For more information on resource labels, see Using resource labels.
6. If you have added a label, click Save.

API

To edit a consent store, use the projects.locations.datasets.consentStores.patch method.

curl

To edit a consent store, make a PATCH request and specify the following information in the request:

• The name and location of the parent dataset.
• The name of the consent store.
• The fields you want to update. The following sample specifies a default time until consents created in this store expire and key and value labels for organizing Google Cloud resources.
• An update mask. The sample below specifies the default_consent_ttl field.

The following sample shows a PATCH request using curl:

curl -X PATCH \
   -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
   -H "Content-Type: application/json; charset=utf-8" \
    --data "{
      'default_consent_ttl' : 'DEFAULT_CONSENT_EXPIRATION_DURATION'
      }
    }" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID?updateMask=default_consent_ttl"

If the request is successful, the server returns a response similar to the following sample in JSON format:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID",
  "defaultConsentTtl": "DEFAULT_CONSENT_EXPIRATION_DURATION"
}

PowerShell

To edit a consent store, make a PATCH request and specify the following information in the request:

• The name and location of the parent dataset.
• The name of the consent store.
• The fields you want to update. The following sample specifies a default time until consents created in this store expire and key and value labels for organizing Google Cloud resources.
• An update mask. The sample specifies the default_consent_ttl field.

The following sample shows a PATCH request using Windows PowerShell:

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

Invoke-WebRequest `
  -Method Patch `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body "{
      'default_consent_ttl' : 'DEFAULT_CONSENT_EXPIRATION_DURATION'
    }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID?updateMask=default_consent_ttl" | Select-Object -Expand Content

If the request is successful, the server returns a response similar to the following sample in JSON format:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID",
  "defaultConsentTtl": "DEFAULT_CONSENT_EXPIRATION_DURATION"
}

Deleting a consent store

Caution: Deleting a consent store also deletes the resources in the consent store. If deleted, these resources cannot be recovered.

The following samples show how to delete a consent store.

Console

To delete a data store:

1. In the Cloud Console, go to the Datasets page.

   Go to the Datasets page

2. Select the dataset containing the data store you want to delete.
3. Choose Delete from the Actions drop-down list for the data store that you want to delete.
4. To confirm, type the data store name and then click Delete.

API

To delete a consent store use the projects.locations.datasets.consentStores.delete method.

curl

To delete a consent store, make a DELETE request and specify the following information in the request:

• The name and location of the parent dataset
• The name of the consent store

The following sample shows a DELETE request using curl:

curl -X DELETE \
   -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
  "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID"

If the request is successful, the server returns the empty response body in JSON format:

{}

PowerShell

To delete a consent store, make a DELETE request and specify the following information in the request:

• The name and location of the parent dataset
• The name of the consent store

The following sample shows a DELETE request using Windows PowerShell:

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

Invoke-WebRequest `
  -Method Delete `
  -Headers $headers `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID" | Select-Object -Expand Content

If the request is successful, the server returns the empty response body in JSON format:

{}

Audit logging

The Consent Management API writes the following types of audit logs:

• Admin Activity: record operations that modify the configuration or metadata of a resource. You can't disable Admin Activity audit logs.
• Data Access: contain API calls that read the configuration or metadata of resources, as well as external API calls that create, modify, or read customer-provided resource data. These logs must be enabled. For example, Data Access audit logs can be used to log what service made an access determination request, what information was provided in that request, and how the API responded to that request. For more information on Data Access audit logs, see Configuring Data Access audit logs. For more information about audit logging in the Cloud Healthcare API, visit Viewing Cloud Audit Logs.

For more information on audit logs for the Consent Management API, see Viewing Cloud Audit Logs.