Download
EstateGuru
Connect (OAUTH2)
Version 1.0 (Draft)
28-Jan-2018
Table of Content
Introduction
2
Integration
3
Authorization
3
Access Token
5
Refresh token
6
Error Codes
7
1
Introduction
EstateGuru Connect API allows 3rd party services to use OAuth2 protocol for getting user
related information from the platform. The API is enough flexible to give opportunity to its
users to grant a 3rd party service a permission without exposing its credentials.
Below you can see abstract overview of the protocol in action.
2
Integration
In order for a 3rd party service to consume API services, a designated client username
and secret should be requested from EstateGuru Platform.
Authorization
In order to get user related information, first client should redirect them to EstateGuru platform to
get user authorization for granting client for certain consumption of information.
To redirect user for authorization, use following url
Authorize URL: https://estateguru.co/api/oauth/authorize
When redirecting user for authorization, client application should construct following post
parameters
Parameter name
Description
requestId
Required: An unguessable random string. This is used to
identify request/response
clientId
Required: A valid client id issued by EstateGuru platform
clientSecret
Required: Your client secret, that you’ve received from
EstateGuru platform, during account registration
redirectUrl
Optional: Client application’s URI for user to be redirected
after authorization process. You can provide your callback
url during client account request from EstateGuru, otherwise
submit it with request.
3
Example Request:
curl https://estateguru.co/api/oauth/authorize \
-X POST \
-d
'requestId=d16509f6-62ef-4902-bba1-912960e00898&clientId=LHV&clientSecret=pBvghzCDU
wcCU6EPh36YSfyKpfhXc9TNqSXjY3SmzD9Y8&redirectUrl=https://example.com/oauth/callback
'
After successful request and user authorization, a valid access token will be returned in
the response
{
"access_token": “fec1e6f2f6c078583756d0c09d7207750baea28dfbc3d4b0f2cb80",
"token_type": "bearer",
"expires_in": 43199,
"refresh_token": “06de603504c1e8437709b0f47d07bed11981fe61b522278a81a9232b7",
"request_id": “d16509f6-62ef-4902-bba1-912960e00898"
}
Note that for every response, you can find corresponding request_id initially submitted in
request object. This is intended behaviour and can be useful for synchronization and proper
handling of response objects.
4
Access Tokens
After receiving valid access token, you can retrieve user information.
Example of request
curl https://estateguru.co/userInformation/userInvestments \
-X POST \
-H "Authorization: Bearer cf96e458-12a1-4854-908d-419a35118363" \
-d 'requestId=d16509f6-62ef-4902-bba1-912960e00898'
After successful validation of bearer token sample response will be as follows.
{
"requestId":
"1313d3df-81d6-45b1-abae-6dc84b71bd16509f6-62ef-4902-bba1-912960e00898",
"currency": "EUR",
"cash": "48872900.14",
"investments": [
{
"change": "0.00",
"investment_amount": "10130.00",
"market_value": "10130.00",
"name": "#5XX Bridge loan (Estonia)",
"principal_left": "10130.00",
"profit": "0.00",
"quantity": "3",
"realized_income": "0.00",
"resourcePath":
"https://estateguru.co/portal/investment/single/EE11111"
}
]
}
5
Refresh Tokens
Once access_token is expired clients can regain a new valid access_token with their
refresh_token received during authorization phase and client credentials.
Example of request with refresh_token
curl https://estateguru.co/userInformation/userInvestments \
-X POST \
-u LHV:pBvghzCDUwcCU6EPh36YSfyKpfhXc9TNqSXjY3SmzD9Y8 \
https://estateguru.co/oauth/token \
-H "Accept: application/json" \
-d "grant_type=refresh_token&refresh_token=f06de603504c1e8ed11981fe61b522278a81a9232b7"
6
Error Codes
Error Id
Code
Description
invalid_token
401
Unable to verify given access token
invalid_grant
400
Unable to verify given refresh_token
Unauthorized
401
Client credentials are invalid
Errors
400
Validation failure (general)
7