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.

get

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

Query parameters

ParameterDescription
Parameter
response_type
Description
Set to code.
Parameter
client_id
Description
ID of your client credentials.
Parameter
redirect_uri
Description
Valid callback URI that was registered when publishing your application. Should be URL encoded.
Parameter
scope
Description
Scopes that the user need to consent to as a space separated list. Should be URL encoded.
Parameter
state
Description
An opaque value used by the client to maintain state between the request and callback. The authorisation server includes this value when redirecting the user-agent back to the client. Highly recommended for preventing cross-site request forgery.

Success response

ParameterDescription
Parameter
code
Description
The authorisation code generated by the authorisation server. To be exchanged with an access token.
Parameter
state
Description
Added if the state parameter was present in the client authorisation request. Will be the exact value received from the client.

Error response

ParameterDescription
Parameter
error
Description
Error code describing the issue.
Parameter
error_description
Description
A more detailed error description.
Parameter
state
Description
Added if the state parameter was present in the client authorisation request. Will be the exact value received from the client.

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
Parameter
content-type
Description
The mediatype of what should be returned. Set to application/x-www-form-urlencoded
Parameter
authorization
Description
Base64 encoded client_id and client_secret. Formatted as Basic <base64-encoded client_id:client_secret>.

Request body

ParameterDescription
Parameter
grant_type
Description
Set to authorization_code.
Parameter
code
Description
The authorisation code received from the authorisation server in step 1.
Parameter
redirect_uri
Description
The same callback URI used in step 1. Should be URL encoded.

Response body

ParameterDescription
Parameter
access_token
Description
Used as a bearer token to call our APIs.
Parameter
refresh_token
Description
Used to obtain new access tokens.
Parameter
token_type
Description
Always Bearer.
Parameter
expires_in
Description
Time in milliseconds until the access_token expires.

Examples

curl -v -X GET '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 more seamless end-user experience, you will need to refresh the token before it expires. The refresh_token is valid for 30 days. After that, the user has to re-authenticate.

post

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

Headers

ParameterDescription
Parameter
content-type
Description
The mediatype of what should be returned. Set to application/x-www-form-urlencoded
Parameter
authorization
Description
Base64 encoded client_id and client_secret. Formatted as Basic <base64-encoded client_id:client_secret>.

Request body

ParameterDescription
Parameter
grant_type
Description
Set to refresh_token
Parameter
refresh_token
Description
The refresh_token received from the authorisation server.

Response body

ParameterDescription
Parameter
access_token
Description
Used as a bearer token to call our APIs.
Parameter
refresh_token
Description
Used to obtain new access tokens.
Parameter
token_type
Description
Always Bearer.
Parameter
expires_in
Description
Time in milliseconds until the access_token expires.

Examples

curl -v -X GET '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