otonomo-docs

Test Drive Vehicle Data from Otonomo

Our connected car data is now accessible for developers

Obtaining Driver Consent

Otonomo's Automotive Data Services Platform offers two types of data: Aggregated vehicle data and personal driver data. Consuming personal driver data by a service 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/oauth/v1/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.

  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.

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/oauth/v1/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/oauth/v1/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 6 months ago

Obtaining Driver Consent


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.