User Consent

In general in-vehicle data (e.g., mileage, fuel level, etc.) is considered personal data and therefore must be processed according to the General Data Protection Regulation (GDPR). Thus, processing such data requires establishing a lawful basis for processing.

For synchronous, OAuth-based consent, technical integration of consent handling is required before you can request in-vehicle data. This section will explain in detail how you can integrate our consent provisioning system in your solutions. On a successful subscription, you receive a subscriptionId, which you need to provide when requesting data. During a subscription, you also must enter a whitelist of allowedRedirectUrls, which we use to redirect the user to your application after finishing the consent provisioning process.

allowedRedirectUrls are a whitelist of redirect URLs that you can provide during a subscription. This list is pre-provisioned, and you as the consumer can choose any of them during the launching of the consent provisioning process. The selected URL is validated against the pre-provisioned whitelist as part of our security policy. Finally, at the end of the consent provisioning, the user is redirected to the selected redirect URL. In case no redirection to the consumer application is needed, this whitelist is optional.

You as consumer may have multiple subscriptions, each uniquely identified by the subscriptionID. The consumer needs to specify what subscription and vehicle identifier the end-user is supposed to provide the consent for. It also means the consumers should persist a mapping between the vehicle identifier number (VIN), the vehicle manufacturer, and the corresponding Caruso subscriptionID. The consent is managed on the subscription level in our platform. Based on the VIN and thus brand of the user’s vehicle, the data consumer can infer which corresponding subscriptionID has to be used for the consent provisioning process.

Below you will find an example screen flow and it would give you an impression on how the users of your application would experience the end-to-end consent provisioning process.

Consent Screens
Consent Provisioning Screen Flow: INSURAC is an example data consumer and "My Vehicle Manufacturer" is an example vehicle manufacturer.

Steps of Consent Provisioning

Consent Flow
System Interaction Diagram: Step 1, 4, and 5 are relevant for integration, the rest is taken care of by Caruso.

Consumers not necessarily need their own application to initiate the consent provisioning process - read more about this in the following steps.

Forward the user to the Caruso consent portal to initiate the consent provisioning process.

We let it up to the consumers to design how they would like to onboard the user (the registered keeper). In case the consumer is in possession of the optional user data, we recommend to pass it on to Caruso upon redirection. Otherwise, the user will have the chance to provide the required information manually when giving consent in the Caruso Consent Portal. Passing more parameters will help to give your user a better experience and saves him from having to type in the information manually. However, the mandatory parameters need to be always supplied by the consumer.

Routing User to Caruso Consent Portal

https://consent.caruso-dataplace.com/provision?consumerId=<insert_your_consumerId_here>&subscriptionId=<insert_your_subscriptionId_here>&vin=<insert_vin_here>&redirectUrl=<insert_your_redirectUrl_here>&email=<insert_email_here>&firstName=<insert_firstName_here>&lastName=<insert_lastName_here>

QUERY PARAMETERS

consumerId required
Query Parameter Your partner id provided by the Caruso Platform.
subscriptionId required
Query Parameter Your subscription id provided by the Caruso Platform.
redirectUrl
Query Parameter Your redirect URL, which is part of the subscription redirect URL whitelist. This parameter is optional and is only needed if you have an application to which the end user should be redirected at the end of the consent provisioning process.
vin
Query Parameter This is the Vehicle Identification Number, the unique ID for the vehicle.
firstName
Query Parameter This is the first name of the owner/ driver of the car.
lastName
Query Parameter This is the last name of the owner/ driver of the car.

The parameter redirectUrl must only be provided if the user should be redirected to your application at the end of the consent provisioning process. If you don’t have an application, or don’t want the user to be redirected to your application at the end, this parameter can be omitted. This case can be particularly interesting for data consumers who do not have their own application and send the link to the Caruso Consent Portal to the end user via other means such as E-Mail or SMS.

The user gets detailed information about what he or she is giving consent. The user can see all the data-items involved, the processing purpose, all the parties involved in the data flow, his or her rights according to GDPR, and all related topics. Once the user is willing to provide consent, he or she can Approve it in the Caruso Consent Portal. On success, the user will be automatically redirected to the vehicle manufacturers’ authorization server. In case the user decides to reject consent, he or she will be forwarded back to the given redirectUrl with an error code and a description.

Redirecting the User to the Application in case of declining Consent

redirectUrl?error=rejected&error_description=user%20rejected%20consent

The given user-consent to Caruso will be stored, but it will be only activated after the user successfully provides consent to the vehicle manufacturer. As a developer, you do not need to do anything technically for this step.

Caruso portal automatically redirects the user to the vehicle manufacturers’ portal. The user needs to use his vehicle manufacturer credentials to log in to the vehicle manufacturer’s portal. After logging in, the user can provide consent to the vehicle manufacturer. Every vehicle manufacturer will have a slightly different implementation of the consent flow, depending on their requirements. Nevertheless, the user will always be able to see for what he or she is giving consent - the data involved, the party and the purpose. As a developer, you do not need to do anything technically for this step.

Step 4: Caruso redirects the User to your Application

Once the user successfully provides consent to the vehicle manufacturer, he or she will be redirected to the Caruso platform. The Caruso platform updates the consent information accordingly and afterward, in case a redirectUrl was provided, redirects the user to your application. Caruso uses the rediectUrl that is used by you when you started the consent provisioning process and is part of your subscriptions’ redirectURLs whitelist. If you did not specify a redirectUrl in step one, the process ends here and the user receives a success message. Step 5 is optional and will be skipped in this case.

Redirecting the User to the Application

redirectUrl?code=<consent_confirmation_code>&consent_id=<consentId>

QUERY PARAMETERS

code required
Query Parameter This confirmation code is used in Step 5 to confirm your retrieval of the consent and to access detailed information of the given consent.
consent_id required
Query Parameter The consent id uniquely identifies the given consent. This identifier is generated by Caruso and forwarded to your application.

In case you provided a redirectUrl, the user has now been forwarded to your specified redirectUrl and you are able to retrieve detailed information about the given consent.

Your application calls the Caruso platform with the confirmation code and your API key. In response, you will receive detailed consent information.

Request: Consent Information Retrieval by the Application

POST https://portal.caruso-dataplace.com/api/consent/provisioning/confirmation/{code} HTTP/1.1

REQUEST PARAMETERS

X-API-Key required
Request Header Every consumer in the Caruso platform receives an API Key upon successful completion of the registration process. This API Key is used by the consumer to make all the data retrieval and other backend calls necessary. API Key is used for authenticating against the platform.
code required
Path Parameter This is a unique code generated by the Caruso platform for a particular consent provisioning process. A data consumer can use this confirmation code to retrieve consent information from the Caruso Platform. After the user has given consent this confirmation code is valid for 10 minutes, and is automatically invalidated after it has been used in the confirmation request. This code is used to confirm the consent in the Caruso platform and enables you to retrieve data for the given VIN.

Response: Consent Information Retrieval by the Application

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "consentId" : "<consentId>",
  "vin" : "<vin>",
  "subscriptionId" : "<your_subscriptionId>",
  "confirmedAt" : "<datetime_of_consent_confirmation>",
  "consentGivenAt" : "<datetime_of_consent_approval>"
}

RESPONSE PARAMETERS

vin required
Response Attribute Vehicle identification number for which the consent has been given.
subscriptionId required
Response Attribute Your subscription id for which the user has given consent.
confirmedAt required
Response Attribute The time when the consent retrieval was confirmed by you.
consentGivenAt required
Response Attribute The time when the consent was given by the user.

In case this confirmation call fails, you will receive one of the following errors:

Http Status Code Error Type Description
401 Unauthorized In case the API key is invalid or the partner identified by the provided API key does not match consent-process partner, a 401 Unauthorized error response is returned.
404 Not Found In case a partner does not exist for the given id, a 404 Not Found error response is returned.
409 Conflict These are the cases a 409 Conflict error response with a meaningful error message will be returned: The consent is already confirmed. The consent process is not in the required state, e.g. the VIN of the user has not been confirmed by the vehicle manufacturer yet. The consent provisioning process has timed out (state change longer than 10 minutes ago)The consent was not given to the vehicle manufacturer.

Standard Error Model

{
  "reasonCode" : "car.401",
  "reasonText" : "Partner identified by provided ApiKey does not match consent-process partner.",
  "url" : "/consent/provisioning/confirmation/<code>",
  "method" : "POST"
}

General Error Handling

The consent process can be interrupted at different points during the process. In all cases where no direct communication between your application and Caruso is established, an error code, as well as a short description, is returned in the redirectUrl. It means for all steps, except the activation API call (Step 5) the redirect of the end-user is used to provide information about the occurred error.

Here are some example error scenarios:

  • The end-user terminates the provisioning process at one point by rejecting consent either to Caruso or to the vehicle manufacturer.
  • The communication is lost between the systems (vehicle manufacturer to Caruso, Caruso to Consumer)
  • The user rejects consent at the Caruso Consent Portal or at the vehicle manufacturers’ authorization server.
  • The user gives consent for a VIN that is not matching the requested VIN.

Caruso will send the errors via the redirectUrl.

Error Notification

redirectUrl?error=<error_code>&error_description=<error_description>&consent_id=<consentId>

As soon as the user gives consent in the Caruso Consent Portal, there will always be a consent id sent in all error and success cases. If the user does not give consent to Caruso, there won’t be any data stored by the Caruso Consent Portal and therefore no consent Id exists. As a result, this attribute is optional and not always included in the response. The following table describes the most common error scenarios, but other errors may also occur.

Error Code Description
scope_mismatch Provided scope does not match the requested scope. If the user does not give consent for all required data items to the vehicle manufacturer, the process will fail with this error code.
rejected In case the user rejects giving consent to Caruso to proceed with the consent provisioning process this error code will be returned.
invalid_request This error might happen in e.g. in case the VIN the user has given consent for in the vehicle manufacturers’ authorisation server does not match the VIN given to Caruso.
conflict This error is returned if the consent process is in a wrong state because of an error during the consent provisioning process.
connection_error The connection to the vehicle manufacturers’ authorization server failed.
communication_timeout The connection to the vehicle manufacturers’ authorization timed out.

In any error cases, you just need to re-initiate the process.