Authentication

VerticalResponse’s API uses OAuth 2.0 for authenticating users and allowing them to authorize an application to access their VerticalResponse data (e.g. contacts, lists, email campaigns etc.), all without sharing their credentials with the application.

Upon registering the application, an application key (aka client ID) and secret are generated. Once obtained, the workflow to authenticate the user and gain their authorization are as follows:

1. Perform a GET request to https://vrapi.verticalresponse.com/api/v1/oauth/authorize?client_id=<app id>&redirect_uri=<redirect_uri> where app id is the client ID of the application and redirect_uri is the URL where an authorization code is to be returned to. For example, the call will look similar to the following:

2.Once VR validates the application, the user will be asked to log in to their VR account to authorize the application to use their VR data.

3.Once the user has successfully entered their credentials and has signed in, an authorization code will be sent to the specified redirect_uri. For example, if the redirect_uri is set to https://www.myapp.com/api/v1/oauth/connect, then the response will look something like:  

where the code is the authorization code.

4.The app then must request an access token  by performing a GET request to https://vrapi.verticalresponse.com/api/v1/oauth/access_token, passing in the client ID, client secret, and the redirect URI with the authorization code just obtained. An example call will be: 

Note: The redirect_uri value used in the auth code and the access token call should be the same. If not the access token call will result in an invalid token result.

5. This will return JSON content similar to the following, containing the access token type and the access token itself. In addition the response also includes the VR userid of the particular VR user:

Currently access tokens do not expire. However access tokens can become invalid if a user revokes access to the application, so you need to handle this condition and get the user to authorize the application again. If this changes in the future to use refresh tokens, we will let you know in advance to prepare for the change. Also, the authorization code is only valid for five minutes, so the access token must be obtained within five minutes of receiving the authorization code.

You can view the client ID and secret for each application at any time by logging in to your VR developer portal, selecting My Account, and clicking on Applications.

Also manually test and try out the various VerticalResponse API calls by navigating to http://verticalresponse.mashery.com/io-docs and selecting VR API from the dropdown.