Overview
The Deletion service allows you to easily request the deletion of personal data from all YaaS services and systems in support of data privacy regulations. When you request a deletion, the Deletion service calls the API Management service to check which services store any personal data for a subject specified by ID and type. Afterward, the Deletion service starts an events chain to delete data from all applicable sources. In response, each service sends a status directly to the Deletion service, which allows you to review the statuses from all services in a single place.
You can also use the Deletion service to get a list of requested deletions and check the details and statuses for a particular deletion. When retrieving a list of requested deletions, you can limit the results to records with a particular status, subject type, or subject ID.
The Deletion service works for these subject types:
- YaaS accounts indicated by the subject type
yaas-account. - CaaS customers indicated by the subject type
caas-customer.
API Reference
/deletions
/deletions
Get a list of deletions.
Security / Access Control:
To access this method, access token must be issued using Implicit Grant flow in the tenant context with hybris.deletion_view scope when you remove caas-customer user. When you remove yaas-account use the Implicit Grant flow without specifying tenant.
Create a deletion request.
Security / Access Control:
To access this method, access token must be issued using Implicit Grant flow in the tenant context with hybris.deletion_manage scope when you remove caas-customer user. When you remove yaas-account use the Implicit Grant flow without specifying tenant.
/deletions/{id}
Get a particular deletion.
Security / Access Control:
To access this method, access token must be issued using Implicit Grant flow in the tenant context with hybris.deletion_view scope when you remove caas-customer user. When you remove yaas-account use the Implicit Grant flow without specifying tenant.
/deletions/{id}/responses
Provides a response to the deletion requests. This endpoint is used by the data privacy-compliant services to provide their status.
Security / Access Control:
To access this method, access token must be issued for client and have hybris.deletion_notify scope to use this resource.
Events
The topic owner client is personaldata.deletion.
| Type | Description | Schema | Payload Example |
| deletion-request | The personal data deletion request for can-delete or delete requests | Download | |
Events details
The Deletion service broadcasts the following events:
| Event | Description | Expected response types |
|---|---|---|
| can-delete | Can the listening service delete any data? |
|
| delete | The listening service must delete the data. |
|
This table describes each of the possible statuses in response to the Deletion service's call:
| Status | Description |
|---|---|
no-data | The service does not handle the given subject type or does not store any personal data related to the subject ID. |
can-delete | The service stores data for the given subject type and ID and can delete it. |
transaction-in-progress | The data privacy-compliant service has pending transactions and therefore cannot delete personal data. The response contains information about how long the system keeps a transaction active. Possible values are:
|
blocked | The data privacy-compliant service successfully blocked the data. The compliant service provides additional information about the retention period. The compliant service is responsible for deleting the data after the retention period expires. |
deleted | The data deletion is successful. |
failed | The data privacy-compliant service cannot perform the operation. The response contains details of the error that occurred. |
Request and retrieve deletions
This tutorial describes how to:
- request deletion of personal data
- retrieve a list of deletions
- filter a list of deletions
- retrieve a single deletion status and its details
Request data deletion
To request the deletion of personal data, perform a POST request on the /deletions endpoint. In the body of your request, provide the dataSubjectId and dataSubjectType, as shown in the example:
{
"dataSubjectId": "C7348248",
"dataSubjectType": "caas-customer"
}
You can select following types:
- yaas-account
- caas-customer
A successful response returns the 202 Accepted status code and contains the ID of the deletion, along with a link to it:
{
"id": "594b78cca0036dff568eeec1",
"link": "https://api.beta.yaas.io/hybris/deletion/v1/deletions/594b78cca0036dff568eeec1"
}
You can use the deletion ID and link provided in the response to perform a GET request to check the status of the deletion process from all services.
Retrieve a list of deletions
You can list all triggered deletions by performing a GET request on the /deletions endpoint.
A successful response returns the 200 OK status code with a body that contains the following fields:
- id - the ID of a deletion
- dataSubjectId - the ID of the subject for which the system removes data
- dataSubjectType - the type of subject for which the system removes data
- user - the user requesting the deletion
- status - the status of a deletion
- createdAt - the date and time of the creation of the deletion
- modifiedAt - the date and time of the last update to the deletion process
- finishedAt - the date and time of the last update to the deletion process
This example shows a typical response:
[
{
"id": "594b78cca0036dff568eeec1",
"dataSubjectId": "c1234",
"dataSubjectType": "caas-customer",
"status": "in-progress",
"createdAt": "2017-06-22T09:59:08.036+0200",
"modifiedAt": "2017-06-22T09:59:54.036+0200"
},
{
"id": "597991375866340014b60294",
"dataSubjectId": "c1234",
"dataSubjectType": "caas-customer",
"status": "finished",
"createdAt": "2017-05-22T09:59:08.036+0200",
"modifiedAt": "2017-05-25T09:59:54.036+0200",
"finishedAt": "2017-05-25T09:59:54.036+0200"
}
]
createdAt field and paged. The default page size is 16.Filter a list of deletions
When retrieving a list of requested deletions, you can limit the results using one or more of these field query parameters:
- status
- dataSubjectId
- dataSubjectType
This example shows a filtered request:
curl -G -i -H "Authorization: Bearer 081-3f1219c6-35wf-4863-87b6-5fccf07e09ba" https://api.beta.yaas.io/hybris/deletion/v1/deletions?status=finished&dataSubjectId=c1234
&dataSubjectType=caas-customer
Retrieve a deletion
To retrieve a specific deletion, perform a GET request on the '/deletions/{id}' endpoint.
A successful response returns the 200 OK status code with the body. The response contains the services field, an array that includes the following fields for each service involved in the deletion:
- service - the name of the service
- status - the status of data deletion within that particular service
- region - the region where that particular service is located
This example shows a request for a specific deletion:
{
"id": "597991185866340014b60293",
"dataSubjectId": "c12345",
"dataSubjectType": "caas-customer",
"status": "finished",
"createdAt": "2017-07-27T07:07:04.124+0000",
"modifiedAt": "2017-07-27T07:09:12.223+0000",
"finishedAt": "2017-07-27T07:09:12.223+0000",
"services": [
{
"serviceBasePath": "/hybris/data-owner-mock/v1",
"status": {
"can-delete": {
"response": "can-delete",
"timestamp": "2017-07-27T07:07:04.891+0000"
},
"delete": {
"response": "deleted",
"timestamp": "2017-07-27T07:07:12.223+0000"
}
},
"serviceRegion": "us"
}
]
}
The status field contains responses for the can-delete phase and for the delete phase as well.
There are following final statuses of the delete request:
- finished - This status indicates that the request was successfully completed and data was removed or blocked
- interrupted - This status indicates that the request was finished but data could not be removed due to pending transaction
- failed - This status indicates that the request was failed due to failed response from the service or no response at all
More over, while request in being processed, following statuses might appear:
- awaiting-can-delete - This status indicates that can-delete event was sent and request is awaiting responses
- awaiting-delete - This status indicates that delete event was sent and request is awaiting responses
Send a deletion response from your service
This tutorial describes how to send a deletion response from your service to the Deletion service.
To send a deletion response from your service, perform a POST request on the /deletions/{id}/responses endpoint, where id is the identifier of a pending deletion.
In the body of your request, provide the attributes listed:
- response indicates the state of data the service stores. For example:
can-delete,deleted, ortransaction-in-progress. - inResponseTo indicates the type of deletion request the service is responding to. For example:
can-deleteordelete. - serviceBasePath specifies the base path of the service sending the response. For example:
/hybris/customer/v1. - serviceRegion indicates the regional location of the service sending the response. For example:
eu.
Payload example:
{
"inResponseTo": "delete",
"response": "deleted",
"serviceBasePath": "/hybris/customer/v1",
"serviceRegion": "eu"
}
A successful response returns the 204 NoContent status code without a body.
Security
The system does not delete personal data immediately after you issue a deletion request, nor does it remove any data directly. Instead, it calls on other data privacy-compliant services to trigger the actual data removal. Additionally, if the specified data is subject to a transaction or retention policy, the system deletes it only after the transaction or retention period ends.
Instead, a deletion request triggers an events chain. All services that listen to the associated "delete" topic and contain a subject's personal data react to those events and respond to the Deletion service with their deletion statuses.
The Deletion service applies a two-phase approach. In the first phase, the service sends the can-delete event and collects information about the listening services' ability to remove data. In the second phase, the service sends the delete event and the data privacy-compliant services must block or remove the data.
The Deletion service supports two subject types:
- YaaS accounts indicated by the subject type
yaas-account. Use this subject type to remove a YaaS user account and the data associated with it. - CaaS customers indicated by the subject type
caas-customer. Use this subject type to remove the data of your customers from services. The Data Protection Officer is responsible for requesting the deletion of such data.
The Deletion service behaves differently for deletion requests for each subject type.
Delete a yaas-account subject type
To remove a yaas-account subject type, acquire the token using the Implicit Grant flow without the tenant context. The service does not require additional scopes. For security, reasons the dataSubjectId must match the user ID of the requester. This prevents removing another user's account.
Delete a caas-customer subject type
To remove a caas-customer subject type, acquire the token using the Implicit Grant flow with the tenant context and appropriate scopes.
- Use the hybris.deletion_view scope to perform GET requests.
- Use the hybris.deletion_manage scope to request a deletion.
yaas-account and caas-customer subject types differently. If you acquire the token without a tenant context, you cannot view nor manage caas-customer deletions. Conversely, if you acquire a token with a tenant context, you cannot view or manage yaas-account deletions.Handle a service callback response
To send a callback response from your service to the Deletion service, acquire the token using the Client Credentials flow with the hybris.deletion_notify scope.
Glossary
| Term | Description |
|---|---|
| personal data | Any data that can lead to the identification of an individual, such as a cultural or economic identity. |
| subject | An entity identified by object type and object ID. Supported types are `yaas-account` and `caas-customer`. |
If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.
Use our private help channel. Receive updates over email and contact our specialists directly.
If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.