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. Open 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 Add label to define optional key and value labels to organize your Google Cloud resources.

7. In Consent Store Configuration 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. Click Create.

API

To create a consent store using the projects.locations.datasets.consentStores.create method, make a POST request and specify the following information in the request:

• The name 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.
• An access token.

curl

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

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.

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 of the parent dataset
• The name of the consent store
• An access token

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 of the parent dataset
• The name of the consent store
• An access token

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.

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
• An access token

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
• An access token

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.

Updating a consent store

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

To update a consent store using the projects.locations.datasets.consentStores.patch method, make a PATCH request and specify the following information in the request:

• 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
• An access token

curl

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

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.

To delete a consent store using the projects.locations.datasets.consentStores.delete method, make a DELETE request and specify the following information in the request:

• The name of the consent store
• An access token

curl

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

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.