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.
Parameter | Description | Required |
---|---|---|
app | Otonomo parameter. The application name as defined in the developer portal. | Yes |
client_id | In accordance with RFC 6749 section 2.2 "The authorization server issues the registered client a client identifier". The client identifier is found in the developer portal. | Yes |
redirect_uri | In accordance with RFC 6749 section 3.1.2: "After completing its interaction with the resource owner, the authorization server directs the resource owner's user-agent back to the client. The authorization server redirects the user-agent to the client's redirection endpoint previously established with the authorization server during the client registration process or when making the authorization request." | Yes |
response_type | In accordance with RFC 6749 section 3.1.1: "The value MUST be one of "code" for requesting an authorization code as described by Section 4.1.1". Otonomo supports only the code method. | Yes |
state | In accordance with RFC 6749 section 4.1.1: "An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter SHOULD be used for preventing cross-site request forgery". | No |
oem | Otonomo parameter. OEM parameter denotes the driver's car make. This parameter is used to address the OEM authentication server. If this parameter is not provided, Otonomo displays the driver a page asking to select the car make (see 2nd screen from left on figure 1). | No |
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.
- Select an OEM from the available list.
- Sign-in to the OEM's platform.
- 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.
Parameter | Description |
---|---|
code | In accordance with RFC 6749, section 4.1.2: "The authorization code generated by the authorization server. The client MUST NOT use the authorization code more than once." |
state | In accordance with RFC 6749 section 4.1.2: "if a "state" parameter was present in the client authorization request. The exact value received from the client." |
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=
Parameter | Description |
---|---|
error | See list of error types on RFC 6749 |
error_description | In accordance with RFC 6749 section 4.1.2.1: "Human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred." |
state | In accordance with RFC 6749 section 4.1.2: "if a "state" parameter was present in the client authorization request. The exact value received from the client." |
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'
Parameter | Description |
---|---|
grant_type | In accordance with RFC 6749 section 4.1.3: Value MUST be set to "authorization_code". |
code | In accordance with RFC 6749 section 4.1.3: "The authorization code received from the authorization server." |
redirect_uri | Same URI as in the authorization request above. |
client_id | In accordance with RFC 6749, section 2.3.1: "the authorization server MAY support including the client credentials in the request-body." The client id is the same as in the authorization code request and is found in the developer portal. |
client_secret | In accordance with RFC 6749, section 2.3.1: "the authorization server MAY support including the client credentials in the request-body." The client secret is found in the developer portal. |
The API call response body:
{"access_token": "ACCESS_TOKEN",
"expires_in": 3600,
"refresh_token": "REFRESH_TOKEN",
"token_type": "Bearer"}
Parameter | Description |
---|---|
access_token | In accordance with RFC 6749 section 5.1: "The access token issued by the authorization server". |
expires_in | In accordance with RFC 6749 section 5.1: "The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated." |
refresh_token | In accordance with RFC 6749 section 1.5 "Refresh tokens are credentials used to obtain access tokens. Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires". The refresh token expires in 180 days. |
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'
Parameter | Description |
---|---|
grant_type | In accordance with RFC 6749, section 6: "Value MUST be set to "refresh_token". |
refresh_token | In accordance with RFC 6749, section 6: "The refresh token issued to the client". The token was issued from the previous call to this endpoint. |
client_id | Same as in the access token request above. |
client_secret | Same as in the access token request above. |
redirect_uri | Same URI as in the authorization request above |
The API returns the following:
{
"access_token": "NEW_ACCESS_TOKEN",
"expires_in": 3600,
"refresh_token": "REFRESH_TOKEN",
"token_type": "Bearer"
}
Parameter | Description |
---|---|
access_token | In accordance with RFC 6749 section 5.1: "The access token issued by the authorization server". |
expires_in | In accordance with RFC 6749 section 5.1: "The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated." |
refresh_token | Same as above. |
Updated over 3 years ago