OAuth 2.0 Integration

Suggest Edits

OAuth 2.0 allows for the secure retrieval of resources while protecting user credentials. Viafoura provides an authentication service which is OAuth 2.0 compliant.

OAuth2 Integration Instructions

You can use your own login system to interact with Viafoura's OAuth 2.0 client credential authentication. All Viafoura needs is a user_id and a session. This section will show you how to generate these from your system using Viafoura in three easy steps.

Here is a login flow diagram to help visualize the interactions:

1007
  1. To get a user_id and a session you will need to use your API key and Site ID.

To create an API key, please login to admin.viafoura.com and go to Settings > API Key. Your Site ID is also listed here and is needed in the next step. Please keep your API key secret as it will be used to create new accounts. You can always delete an old key and create a new one.

  1. An OAuth2.0 access token must be generated using your new API key created in step 1, through HTTP Basic Authentication with your Site ID as the user and the API Key as the password. Using Curl, it would look like this:
curl --user YOUR_SITE_ID:YOUR_API_KEY -d grant_type=client_credentials -d scope=accounts https://api.viafoura.co/oauth2/token
=> {"access_token":"9MRSxm+GZwLfRKLn1luFrJvUP5A=","token_type":"bearer","expires_in":3600,"scope":"accounts"}

You will now submit this OAuth2 bearer token with an HTTP Authorization header along with your systems user ID to get a Viafoura user_id and session. The process below should be performed each time a user logs in to receive a valid session for that user.

Please note in the example below, YOUR_OWN_USER_ID should not be a static admin user ID from Viafoura. It should be a dynamic, unique user_id your system has assigned to whichever user is trying to log in at that point in time.

curl -H "Authorization: Bearer 9MRSxm+GZwLfRKLn1luFrJvUP5A=" -d id=YOUR_OWN_USER_ID -d "name=John Doe" -d "[email protected]" "https://api.viafoura.co/rest/v1/accounts/login"
=> {"user_id":7000000003119,"session":"o52l4itrv8q4p8n4amsou1c567"}

The login endpoint is:

https://api.viafoura.co/rest/v1/accounts/login

It looks for the parameters:

  • id which would be your own system's user ID (required)
  • name the user's name to be shown (required)
  • email the user's email (optional)

The login endpoint will create a non-existing user and will update an existing user if the details have changed.

Please note that sessions expire after 12 hours of user inactivity, and immediately when the user is logged out of Viafoura.

To log a user out, you would need to make the following call:

curl -H "Authorization: Bearer 9MRSxm+GZwLfRKLn1luFrJvUP5A=" -d "session=o52l4itrv8q4p8n4amsou1c567" "https://api.viafoura.co/rest/v1/accounts/logout"

The logout endpoint is:

https://api.viafoura.co/rest/v1/accounts/logout

Looks for the parameters:

  • session the session passed back from a login call. (required)
  1. Utilizing the user_id and session obtained from step 2, The Viafoura
  • id is used to identify our
  • data-uid your user_id.
  • data-sid your session.
<script id="viafoura-platform" data-uid="7000000003119" data-sid="o52l4itrv8q4p8n4amsou1c567">
(function(v,s){v.type='text/javascript';v.async=!0;
v.src='//cdn.viafoura.net/vf.js';;
s.parentNode.insertBefore(v,s)}
(document.createElement('script'),document.getElementsByTagName('script')[0]));</script>

To issue an AJAX logout through JavaScript you can use the following:

viafoura.publish('user.logout');

Please go here to see the JavaScript calls needed to listen to login events:

📘

Note

To hide Viafoura's login/logout options, please change the settings in the Admin > Commenting Tool.

Updated over 3 years ago