APIs

Authorisation

Overview

To allow access to Volvo Cars’ data and features our APIs implement the OAuth 2.0 authorisation framework. End-users delegate the access of their data to your application through their Volvo ID account.

To start the authorisation process you need to have client credentials for the Volvo ID identity system. This is done by publishing your application on your account page. Once the publishing process is done, we will send you the client credentials needed to continue. The client credentials consist of; a client_id and a client_secret.

To try out the APIs without the need for publishing, you can use our test access tokens. Visit your account page to generate or view the tokens.

Authorisation code flow

The following steps describe the process of getting an access token from the end-user using the Authorisation code flow. In the future, we plan to support more types of OAuth2 authorisation flows.

1. Redirect end-user to the Volvo ID login page

Redirect the end-user to the Volvo ID login page. On the Volvo ID login page, the end-user will authenticate and be asked to consent to the requested scopes for your application. After authorisation, the end-user will be redirected back to your application’s callback URI. An authorisation code will be returned as a query parameter in the URI.

url

https://volvoid.eu.volvocars.com/as/authorization.oauth2

Query parameters

ParameterDescription

Success response

ParameterDescription

Error response

ParameterDescription

Examples

https://volvoid.eu.volvocars.com/as/authorization.oauth2?response_type=code&client_id=<your-client-id>&redirect_uri=<your-redirect-uri>&scope=<api-scopes>&state=<your-client-state>

2. Exchange code for an access token

Exchange the authorisation code for an access token. The access_token is used as a bearer token to call our APIs.

post

https://volvoid.eu.volvocars.com/as/token.oauth2

Headers

ParameterDescription

Request body

ParameterDescription

Response body

ParameterDescription

Examples

curl -v -X POST 'https://volvoid.eu.volvocars.com/as/token.oauth2' \
-H 'content-type: application/x-www-form-urlencoded' \
-H 'authorization: Basic <base64-encoded-client-credentials>' \
-d 'grant_type=authorization_code&code=<authorisation-code-from-step-1>&redirect_uri=<redirect-uri-from-step-1>'

3. Refresh the access token

The access_token is only valid for 60 minutes. To create a seamless end-user experience, you will need to refresh the access token before it expires.

By default, refresh token rotation is enabled. Each time you call the Refresh endpoint, a new refresh token is created, and the old token is invalidated. If not rotated, the refresh_token is valid for 7 days. After that, the user has to re-authenticate.

post

https://volvoid.eu.volvocars.com/as/token.oauth2

Headers

ParameterDescription

Request body

ParameterDescription

Response body

ParameterDescription

Examples

curl -v -X POST 'https://volvoid.eu.volvocars.com/as/token.oauth2' \
-H 'content-type: application/x-www-form-urlencoded' \
-H 'authorization: Basic <base64-encoded-client-credentials>' \
-d 'grant_type=refresh_token&refresh_token=<refresh-token-from-step-2>'

Scopes

Endpoints in our APIs requires end-user consent in the form of scopes, this allows our users to have detailed access control of their data and vehicles. Each functionality or data point requires a specific scope. Scopes needed to use an endpoint is specified in the documentation for that endpoint.

Authorisation/Overview