OAuth 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 Provisioning Screen Flow: INSURAC is an example data consumer and "My Vehicle Manufacturer" is an example vehicle manufacturer.

Steps of Consent Provisioning

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.

Step 1: Redirect your user to the Caruso Consent Portal

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>

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.

Step 2: User provides Consent in the Caruso Consent Portal

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.

Step 3: Caruso redirects the User to the Vehicle Manufacturer’s Authorization Server to provide Consent

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>

Step 5: You retrieve consent information from the Caruso Platform (optional)

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

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>"
}

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

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.

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