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 firstname.lastname@example.org
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:
- Redirect the user to our oauth webpage with some parameters which describe what kind of rights you are asking for, and a redirect URI
- User browser send the user back to your redirect URI with an authorization code (if approved by user)
- 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.
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.
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.
|client_id||int||Your client ID, this avoids exposing your API key to the user. We will provide you this on request|
|redirect_uri||string||This must match the redirect_uri we have on file for your ID.|
|response_type||string||Must be set to "code" (defaults to this value if none set).|
|state||string||This is an optional field which adds a state value to the redirect URI and future returned token calls.|
|scope||string(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.|
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:
|state||The state string provided by the original Auth call.|
|code||The user's Authorization code. You can use this to retrieve the user's token.|
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:
|grant_type||Must be "authorization_code" (Defaults to this value if none set).|
|client_id||Your client ID|
|client_secret||Your API Key|
|code||The user's authorization code retrieved in the previous step|
|redirect_uri||Your redirect URI, the user's token will be returned to this address.|
This call returns a JSON object with the following items:
|user_token||The user's token|
|token_type||Bearer token, allows you to authenticate as the bearer.|
|state||State 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
|user_id||The numeric ID of the ABRP user account|
|full_name||The user full name (as given at registration)|
|The user email (as given at registration).|