Creating and updating user consents

This page describes how to create, update, and revoke user consents.

Your application records the consent artifacts and consents separately. The Consent Management API stores sensitive data pertaining to a user's consent as a ConsentArtifact. A ConsentArtifact can include signature timestamps and images of signatures or other documents that act as "proof" of consent.

The Consent Management API stores non-sensitive consent data as Consent objects. A Consent includes an opaque user ID, the consent policies granted by the user, and the status of the consent policies.

Because consents and consent artifacts have distinct resource paths, their permissions can be set independently to minimize access to sensitive consent data in consent artifacts.

Consents support an expiration duration that enables you to configure when consent expires and is no longer valid. The expiration duration can be set to a specific date or a time period, such as one year.

During consent store creation, you can configure a default expiration duration for the consent store. During consent creation, you can configure an expiration duration for the consent. The expiration duration set during consent creation overrides the default duration set for the consent store.

Consents can be created in either ACTIVE or DRAFT states. Consents in the ACTIVE state are used by the Consent Management API to make access determinations. Consents in the DRAFT state are only used in access determinations if specified in an access determination request. You can change the state from DRAFT to ACTIVE or REJECTED by updating the consent.

To record a user consent, create a consent artifact using the projects.locations.datasets.consentStores.consentArtifacts.create method and then link the consent artifact to a consent created using the projects.locations.datasets.consentStores.consents.create method.

The samples in this page assume that you have created a consent store and configured consent policies.

A consent artifact stores sensitive data pertaining to a user's consent. A consent artifact can include a user's contact information, signature timestamps, and images of signatures or other documents that act as "proof" of consent.

To create a consent artifact, use the projects.locations.datasets.consentStores.consentArtifacts.create method. Make a POST request and specify the following information in the request:

  • The name of the parent consent store
  • A unique and opaque user ID that represents the user who provided the consent
  • The user's signature, optionally including the signature image, timestamp, and other metadata. This image can be specified as an image location in Cloud Storage or as a string of raw bytes.
  • An optional guardian or witness signature
  • Optional images or documents acting as "proof" of consent, such as a signature image, images capturing the screens of a mobile consent flow, or a signed PDF document. These images can be specified as a location in Cloud Storage or as a string of raw bytes.
  • An identifier for the consent information that the user was shown
  • Optional metadata related to the user's consent
  • An access token

A consent stores non-sensitive data, including opaque user IDs, the consent policies granted by the users, and whether the consent policies are currently valid.

To create a consent, use the projects.locations.datasets.consentStores.consents.create method. Make a POST request and specify the following information in the request:

  • The name of the parent consent store.
  • A unique and opaque user ID that represents the user who provided the consent.
  • One or more authorization policies, each with a set of RESOURCE attribute values and an authorization rule expressed in Common Expression Language (CEL) that describe the user's intent with previously created attribute definitions. The following restrictions to the CEL apply:
    • You can only define a maximum of 10 logic operators.
    • You can only use AND (&&), OR (||), and IN operators.
  • The REST path to the corresponding consent artifact (returned upon creation of the consent artifact).
  • An optional consent state, either DRAFT or ACTIVE. If you do not specify the state, the consent is created in the ACTIVE state.
  • An optional expiration duration for the consent, defined as either a date or a time period. This value must be provided in seconds and suffixed with the letter s. For example, 86000s. This value overrides the expiration duration configured for the consent store. If you don't configure an expiration, the resource inherits the default expiration duration from the consent store. If an expiration duration isn't specified for either the resource or the store, the consent resource doesn't expire.
  • An access token.

The following samples show how to get a consent. For more information, see projects.locations.datasets.consentStores.consents.get.

To get a consent, make a GET request and specify the following information in the request:

  • The name of the parent dataset
  • The name of the consent store
  • The name of the consent
  • An access token

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

To list the consents in a consent store, use the projects.locations.datasets.consentStores.list method.

Updating consents

You might need to update the state of consents over time. You can do this by changing the consent state. Every update and change of state generates a new revision of the consent. Previous revisions are accessible by appending @{revision_id} to the consent's resource name.

Updating consents

To update an active or draft consent's userId, policies, consentArtifact, or revokeConsentArtifact fields, use the projects.locations.datasets.consentStores.consents.patch method. A new revision is committed with the changes and set to the current state.

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

  • The REST path of the consent to update
  • The fields to update
  • An update mask
  • An access token

Activating consents

To change the state of a consent from DRAFT to ACTIVE after the user accepts the consent, use the projects.locations.datasets.consentStores.consents.activateConsent method. A new revision is committed with state ACTIVE. When the state of the consent is ACTIVE, the consent is included in access determination requests.

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

  • The REST path of the consent to activate
  • The REST path to an optional artifact to document why the consent was activated
  • An access token

Revoking and rejecting consents

To change the state of a consent from DRAFT to REJECTED, for example, if the user indicates that the consent is not acceptable, use the projects.locations.datasets.consentStores.consents.reject method. When the state of a consent is REJECTED, the consent isn't included in access determination requests.

To change the state of a consent from ACTIVE to REVOKED, for example if a user requests to void a previously granted consent, use the projects.locations.datasets.consentStores.consents.revoke method. A new revision is committed with state REVOKED. Consents with a state of REVOKED aren't included in access determination requests. You can create an optional artifact that is associated with the consent to document why the consent was revoked. Revoking a consent doesn't delete the consent.

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

  • The REST path of the consent to revoke
  • The REST path to an optional artifact to document why the consent was revoked
  • An access token