Private Ownership-Obtaining Driver Consent

Otonomo's Automotive Data Platform offers two types of data: Aggregated vehicle data and personal driver data. Consuming personal driver data by a Workspace or application requires the driver to grant consent for sharing data.

This document provides information on how to obtain access to personal vehicle data.
The process is tightly based on industry standards OAuth 2.0 (RFC 6749) and OpenID Connect.

Table of Content

Overview
Step 1: Embed an Authorization Link in Your Application
Step 2: Obtain an Authorization Code
Driver Consent is Granted
Driver Consent is not Granted
Step 3: Exchange the Authorization Code for an Access Token
Refresh Your Access Token

Overview

Otonomo's consent portal allows drivers to selectively choose what data they would like to share with your application. You'll need to embed the portal into your application in order for drivers to access the list of data attributes you're requesting.

The consent portal includes the following:

                                    Figure 1:  typical driver consent experience

The entities involved in the process and their oAuth 2.0 roles:

                                       Figure 2: consent flow entities

Step 1: Embed an Authorization Link into Your Application

The first step in obtaining driver consent is to embed an authorization link within your Client App.

https://consent.eu.otonomo.io/v1/oauth/authorize?response_type=code
&app={service_name}
&client_id={client_id}
&redirect_uri=(redirect_uri}
&response_type=code
&state={state}

https://consent.eu.otonomo.io/oauth/v1/authorize?response_type=code
&client_id={client_id}
&redirect_uri={redirect_url}
&response_type=code
&app={service_name}
&state={state}
&oem={oem_name}

Each part of the hyperlink must include your specific information. Below is an explanation of each section.

Step 2: Obtain an Authorization Code

Now that you have embedded the link into the Client App, you will be redirected to the consent portal. The steps you will complete in this portal are similar to the steps a driver will complete to provide consent to share their data.

1. Select an OEM from the available list.
2. Sign-in to the OEM's platform.
3. The list of requested data attributes will appear here. Press "Allow" to provide consent and "Cancel" to reject consent.

Upon completion of the consent dialog, an HTTP redirect response is returned from Otonomo. The Client App is redirected to the Application Server endpoint (for further reading on authorization code, see RFC 6749 section 1.3.1).

Driver Consent is Granted

After you've pressed allow, you will be redirected back to the original redirect URI you provided. Within this redirect URI, you will also receive an authorization code. This code will be used as an exchange for an access token in the next step.

HTTP/1.1 302 Found
Location: https://myapp.com/callback
?code=AUTHORIZATION_CODE_UNIQUE_STRING
&state=tryeda823

❗️

Authorization code expiry

The authorization code will expire after ten minutes.
Make sure that you follow step #3 within that period.

Driver Consent is not Granted

In case the driver has declined access or error has occurred, the following response will be issued.

HTTP/1.1 302 Found
Location: https://myapp.com/callback
?error=access_denied
&error_description=The%20driver%20denied%20access
&state=

Step 3: Exchange the Authorization Code for an Access Token

So far, you've embedded the portal into your application and drivers have the ability to share their data. Once you receive consent from a driver, you can obtain an access token that will allow you to request personal driver data from our APIs.

You'll need to exchange the authorization code you received in the previous step for an access token.
This process uses REST API (the previous process used HTML). Otonomo's token endpoint is used to exchange the Authorization Code with an Access Token. The retrieved Access Token will be used to get vehicle data (e.g. on Vehicle Status endpoint).

🚧

Please note that the token endpoint uses a client secret. We thus recommend not to use this endpoint from the client app.

POST \
https://api.eu.otonomo.io/v1/oauth/token/ \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=authorization_code
&code=AUTHORIZATION_CODE_UNIQUE_STRING
&redirect_uri=http://myapp.com/callback
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET'

The API call response body:

{"access_token": "ACCESS_TOKEN", 
  "expires_in": 3600, 
  "refresh_token": "REFRESH_TOKEN", 
  "token_type": "Bearer"}

Refresh Your Access Token

The Access Token has limited use time as defined by the expires_in parameter. To renew the token, use the following REST API call:

POST \
https://api.eu.otonomo.io/v1/oauth/token/ \
-d 'Content-Type=application%2Fx-www-form-urlencoded
&grant_type=refresh_token
&redirect_uri=http://myapp.com/callback
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET
&refresh_token=REFRESH_TOKEN'

The API returns the following:

{
    "access_token": "NEW_ACCESS_TOKEN",
    "expires_in": 3600,
    "refresh_token": "REFRESH_TOKEN",
    "token_type": "Bearer"
}