Connecting to the APIs

You are here

Introduction

This tutorial explains how to connect to both Reviso APIs (REST and SOAP) using Agreement Grant Tokens and App Secret Tokens, allowing app and integration partners to access data in Reviso user agreements without having to store user credentials.

Notes and requirements

The end-user needs to be set up with the permissions required by the app. The default app created when using our developer signup form requires the Superuser role. See more on permissions and roles.

Administrators: When granting an app access on behalf of a client, you must use the credentials for the superuser of the actual agreement. The owner of the individual agreement will have received these credentials in a welcome email when the agreement was created. You as an administrator cannot install the app using your administrator credentials.

Connecting in 3 steps

To get started, you need to complete 3 steps:

  • Sign up for a developer agreement
  • Obtain your App Secret Token and an Agreement Grant Token
  • Connect to Reviso via REST or SOAP

Read along for a detailed explanation.

Step 1: Sign up for a Developer Agreement

Go to the Developer homepage and sign up for a developer agreement. This agreement will have one pre-registered app that you can start using right away. You can also create more if you like. Please note that this initial app will be set to require the Superuser role.

After registering you will receive a mail with login credentials for your new developer agreement.

Step 2: Obtain an Agreement Grant Token

Log into your Reviso developer agreement and go to the Developer tab (top left corner).

Copy the request URL of your app:

    https://app.reviso.com/api1/requestaccess.aspx?appId=<PublicAppToken>&locale=<locale-code>

We support translating the Request Access page. This is done by appending a "locale" query string to the /requestaccess.aspx request. The following codes are supported: en-GB, de-DE, es-ES, it-IT.

Note: If you want to test and explore the functionality of Reviso, sign up for a trial agreement in the country of your primary user base and test against this. To prolong the trial period of your test agreements, please contact us at api@reviso.com.

Manual delivery of Agreement Grant Token

Send the request access URL to the end-user. When the end-users click the link, they are taken to the Grant access page where they can enter their agreement credentials and grant the app access to their agreement data.

After granting access to the app, end-users are presented with the created token which they need to copy and send to you.

Automated delivery of Agreement Grant Token

To automatically obtain generated Agreement Grant Tokens, you need to set up an endpoint in your solution that is capable of receiving the token from a GET request where the token is supplied in the query string.

To redirect end-users, you must include a redirectURL parameter in the link you supply to end-users. The redirect URL can contain a querystring where you can specify additional information you may need to identify a user on your end.

Example of the redirect URL parameter:

    redirectUrl=https://www.example.com%3userIdInMySystem=123

Example of a complete request URL including a redirect

    https://app.reviso.com/api1/requestaccess.aspx?appId=<PublicAppToken>&locale=en-GB&redirectUrl=https://www.example.com%3FuserIdInMySystem=123

When end-users click the link, they are taken to the Grant access page. After granting access, users are redirected to the URL you supplied with the fresh Agreement Grant Token appended to the querystring.

Example

    https://www.example.com?userIdInMySystem=123&token=<GeneratedAgreementGrantToken>

Step 3: Connect to Reviso

Once you have obtained an Agreement Grant Token, there are two ways of connecting to Reviso: Either using REST, or using a SOAP call.

Using REST

1. Add these three headers to your requests:

  X-AppSecretToken: <TheAppSecretToken>
  X-AgreementGrantToken: <TheAgreementGrantToken>
  Content-Type: application/json

2. Issue a GET to https://rest.reviso.com/customers and inspect the response to validate that everything is working.

Using SOAP

Use our WSDL definition and the auto-generated documentation. Also check out the details in the ConnectWithToken method.

Note that in the section below, "token" refers to the Agreement Grant Token returned when installing the app, and "appToken" refers to the App Secret Token from the Developer tab:

  <ConnectWithToken xmlns="http://e-conomic.com">
    <token>string</token> <!-- Agreement Grant Token -->
    <appToken>string</appToken> <!-- App Secret Token -->
  </ConnectWithToken>

Remember to enable cookies in your SOAP client library.