ABRP OAuth2 API

Created with Sketch.

OAuth2 provides a means of authenticating users easily, and providing a secure and convenient way to identify and authenticate the user with Iternio. To set up OAuth2 with Iternio you will need an API key, and to provide us with a redirect URL and Application name. To get set up, send us an email at contact@iternio.com

OAuth2 is a standard procedure which may seem complicated because there are several actors and parameters, but the “standard” flow is quite straightforward. There are many tutorials on the web; check out e.g. https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2

The standard flow we support is basically:

  1. Redirect the user to our oauth webpage with some parameters which describe what kind of rights you are asking for, and a redirect URI
  2. User browser send the user back to your redirect URI with an authorization code (if approved by user)
  3. Your app or preferably your server calls our server and exchange the authorization code for a user token

This token is what is being used to authenticate the user for future use, for example to send telemetry (live data) to us.

ABRP Scopes

A scope in OAuth2 is simply a right which the user can grant or deny to you. The default scope (no scope) in ABRP includes letting the application read the user’s ID (just an internal number), full name and email address. The remaining scopes are

  • “set_telemetry” – allow the app to submit telemetry data for a certain vehicle owned by the user. The vehicle selection is done by the user in the OAuth2 approval page.
  • “get_telemetry” – allow the app to read the latest telemetry from the user.
  • “get_plan” – allow the app to read out the latest plan which the user has created.

Authorization Call

The first call made returns an HTML page on which the user can log in and approve the use of your application. If this HTML page is opened in the user’s default browser, their login may be cached and simplifies the process further.


KeyDatatypeComment
client_idintYour client ID, this avoids exposing your API key to the user. We will provide you this on request
redirect_uristringThis must match the redirect_uri we have on file for your ID.
response_typestringMust be set to "code" (defaults to this value if none set).
statestringThis is an optional field which adds a state value to the redirect URI and future returned token calls.
scopestring(list)Comma-separated list of items you wish to request permission for. Currently supported are: get_telemetry, set_telemetry, get_plan. If this is omitted, the token only gives the right to read the user ID, email and full name of the user.

https://web.abetterrouteplanner.com/oauth/auth?client_id=<your_client_id>&scope=<your scope>&response_type=code&redirect_uri=<your_redirect_uri>

Instead of web.abetterrouteplanner.com you can use abetterrouteplanner.com directly, but the web prefix ensures that it opens in a browser and not the ABRP app.

Once the user approves the request you will receive the following at your redirect URI:


KeyComment
stateThe state string provided by the original Auth call.
codeThe user's Authorization code. You can use this to retrieve the user's token.

https://your_redirect.uri?state=<state_provided>&code=<returned_code>

Token Retrieval Call

Once you have received an authorization code from the user, you can then retrieve the token. This token can be stored and reused as many times as needed. The following fields are needed to retrieve the user’s token:


KeyComment
grant_typeMust be "authorization_code" (Defaults to this value if none set).
client_idYour client ID
client_secretYour API Key
codeThe user's authorization code retrieved in the previous step
redirect_uriYour redirect URI, the user's token will be returned to this address.

https://web.abetterrouteplanner.com/oauth/token?client_id=<your_client_id>&client_secret=<your_api_key>&code=<auth_code>&redirect_uri=<your_redirect_uri>

This call returns a JSON object with the following items:


KeyComment
user_tokenThe user's token
token_typeBearer token, allows you to authenticate as the bearer.
stateState value input above in the auth call and associated with the token.

And that’s it! From here you can include the user’s token on calls to the various services we provide that need to identify or authenticate a user.

User Info Retrieval Call

After you have obtained the token for the user, you are all set in terms of authentication. Now, to retrieve user information, use the “me” endpoint with the token:

https://web.abetterrouteplanner.com/oauth/me?access_token=<the user token>&api_key=<your api key>

The default output of the call is a JSON object containing


KeyComment
user_idThe numeric ID of the ABRP user account
full_nameThe user full name (as given at registration)
emailThe user email (as given at registration).