Viafoura

The Viafoura Documentation Hub

Welcome to the Viafoura documentation hub. You'll find comprehensive guides and documentation to help you start working with Viafoura as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    API Reference

OAuth 2.0 Integration

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.

To use OAuth 2.0 authentication with Viafoura, the following must occur:

  1. Obtain a temporary access token by requesting authorization with our OAuth 2.0 compliant server.
  2. Request a protected resource using the aforementioned access token.
  3. The resource server will verify the access token before providing the resource.

If the access token has expired, an error will return when requesting the protected resource, and a new access token must be requested.

Example:

During onboarding or by contacting support, you will receive a clientId and clientSecret, as well a list of scopes that are accessible to you.

Using a provided endpoint to one of our OAuth 2.0 compliant servers, one can perform the following cURL:

curl
-X POST {ENDPOINT}
--user {CLIENT_ID}:{CLIENT_SECRET}
-H "Content-Type: application/x-www-form-urlencoded"
-H "Accept: application/json"
-d grant_type=client_credentials
-d scope={SCOPE}
-v

If successful, this will return a JSON object with an access_token field. This token is the token to be used when requesting secure resources elsewhere.

In order to use the token, attach it as an 'Authorization: Bearer' header to any request for a secure resource.

Example:

curl
-H 'Authorization: Bearer {TOKEN}'
-i '{baseURL}/profile/badge'
-XPUT
-d '{"description":"Users with active subscriptions", "label":"subscriber"}'

If the token has expired, an error will be returned, and you will have to refresh the token by appealing to the OAuth 2.0 compliant server again.
The expiration is encoded into the token, and you can determine when it expires by decoding it from base64.

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:

  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.

curl -H "Authorization: Bearer 9MRSxm+GZwLfRKLn1luFrJvUP5A=" -d id=YOUR_OWN_USER_ID -d "name=John Doe" -d "email=john@example.com" "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 <script> tag now must include these values to allow a user to be logged in. To do this, we need to add an id, data-uid, and data-sid inside the viafoura <script> tag.

    • id is used to identify our <script> tag. Please do not change this.
    • 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.

OAuth 2.0 Integration


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.