ABRP OAuth2 API

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

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.
scopecomma-separated stringOptional field to request higher-than-default permissions for the token. Allowed scopes are one or more of
- set_telemetry (push vehicle data to ABRP)
- get_telemetry (get vehicle data from ABRP)
- get_plan (get information on the latest plan for the user)
typecodestringOptional typecode string to use for a new vehicle, if the user chooses to create a new
vehicle_namestringOptional vehicle name string to use for a new vehicle, if the user chooses to create a new
https://abetterrouteplanner.com/oauth/auth?client_id=<your_client_id>&scope=<requested_scope>&response_type=code&redirect_uri=<your_redirect_uri>

The requested scopes have different effects. Get Telemetry allows you to retrieve the user’s telemetry from our server, Get Plan lets you retrieve a compressed version of the most recent plan created by the user, and Set Telemetry lets you upload data points for the user.

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.
auth_codeThe user's Authorization code. You can use this to retrieve the user's token.
https://your_redirect.uri?state=<state_provided>&auth_code=<returned_auth_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
https://abetterrouteplanner.com/oauth/token?client_id=<your_client_id>&client_secret=<your_api_key>&code=<auth_code>

This call returns a JSON object with the following items:

KeyComment
access_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://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).