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.
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
To get started, you need to complete 3 steps:
Read along for a detailed explanation.
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.
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.
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.
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>
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.
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.