Connecting to the APIs
You are here
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: Administrators can create grants, but they only have access to the studio module
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:
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 email@example.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:
Example of a complete request URL including a redirect:
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.
Note: Please be aware that the Grant Tokens expire after 360 days, at which time you must repeat the request process to facilitate continued use.
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.
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.