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 the test access tokens page to generate tokens.
Authorisation code flow
The following steps describe the process of getting an access token from the end-user using the Authorisation code flow specification.
We plan to support more types of OAuth2 authorisation flows in the future.
For a sample implementation, see our OAuth2 Code Flow sample on GitHub.
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
| Parameter | Description |
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
| Parameter | Description |
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
| Parameter | Description |
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
| Parameter | Description |
Parameter content-type | Description Format of the data sent to the server. 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
| Parameter | Description |
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
| Parameter | Description |
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 seconds until the access_token expires. |
Examples
curl 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 has a short lifespan. 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
| Parameter | Description |
Parameter content-type | Description Format of the data sent to the server. 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
| Parameter | Description |
Parameter grant_type | Description Set to refresh_token |
Parameter refresh_token | Description The refresh_token received from the authorisation server. |
Response body
| Parameter | Description |
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 seconds until the access_token expires. |
Examples
curl 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.