OAuth2

Terms:
1. CLIENT_KEY
Key(Similar to username) Given for REST client (react js) to connect with Server

2. CLIENT_SECRET
Secret (similar to password) to be used with key to connect with Server.

3. USER_CREDENTIALS
Username and password entered by User on login screen

4. ACCESS_TOKEN
Token obtained from Server using User Credentials. Server will identify the User based with
this Token. Typically expires in 1 hour.

5. REFRESH_TOKEN
This token will be obtained along with Access Token. It will have longer expiry time than
Access Token. Typically 24 hours. If Access Token is expired, a new token can be obtained from
server using this Refresh token.

6. BASE64_CLIENT_CREDENTIALS
encode CLIENT_KEY and CLIENT_SECRET separated by colon (​:​) with Base64
Example:​ If client key is “​123456​” and client secret is “​abcdef​” then base Base64 encoded
value of “​123456:abcdef​” is “​MTIzNDU2OmFiY2RlZg==​”.

7. BASE_URL
https://example.com

8. Test Credentials
CLIENT_KEY:​ ​live-test
CLIENT_SECRET:​ ​asdfasdfasdfasdfasdfasdf

Notes:
1. If any API returns status code 5XX (500, 503 etc) then it is server faultAPIs:
2. If any API returns status code 4XX (400, 401, 403 etc) then there is an issue in request.
Reasons can be Invalid url (404), Unauthorized(401), Invalid data (400).
1. Security APIs:

1.1. Signup

Property Type Constraints

email​* String Valid email, max 50 characters

password​* String

confirm_password​* String Same as ​password

username* String Valid username, max 50 characters

Request
POST /api/signup
Headers:
Content-Type: application/json
{
"username": "example",
"email": "user@example.com",
"password" : "123456",
"confirm_password": "123456"
}

Response
201 If Signup success. An email with verification code will be sent to user

400 Username already exists

{
"status": "BAD_REQUEST",
"message": "Validation Error",
"timestamp": "2017-11-20T15:00:19.648+08:00",
"errors": [
{
"field": "username",
"message": "Username already registered"
}
]
}

400 Invalid email

{
"status": "BAD_REQUEST",
"message": "Validation Error",
"timestamp": "2017-08-25T06:15:35.062Z",
"errors": [
 {
"field": "email",
"message": "Invalid Email"
}
]
}

400 Email already exists

{
"status": "BAD_REQUEST",
"message": "Validation Error",
"timestamp": "2017-08-25T06:17:40.389Z",
"errors": [
{
"field": "email",
"message": "Email already registered"
}
]
}

400 password and confirm_password don’t match

{
"status": "BAD_REQUEST",
"message": "Validation Error",
"timestamp": "2017-08-25T06:18:38.171Z",
"errors": [
{
"message": "Passwords do not match"
}
]
}

1.2. Verify Email

Request
PUT /api/verify-email?token=​TOKEN_SENT_ON_MAIL

Response
200 Token verified successfully (No response JSON will be returned. Status code is enough)
400 Invalid token (No response JSON will be returned. Status code is enough)

1.3. Login
Save the ​ACCESS_TOKEN​ and ​REFRESH_TOKEN​ obtained from successful login to access any
data from server.

Request
POST /oauth/token
Headers:
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64_CLIENT_CREDENTIALS
Form Data:
"Key":"grant_type", "value":"password"
"Key":"client_id", "value":"CLIENT_ID"
"Key":"username", "value":"USER_CREDENTIALS.USERNAME"
"Key":"password", "value":"USER_CREDENTIALS.PASSWORD"

Response
200 Returns ​ACCESS_TOKEN​ and ​REFRESH_TOKEN​ as below
{
"a ​ ccess_token"​ :
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MDMyNTI1MjUsInVzZXJfbmFtZSI6ImlicmFo
aW0uYXduQGdtYWlsLmNvbSIsImF1dGhvcml0aWVzIjpbIlJFQURfUFJJVklMRUdFIiwiV1JJVEVfUFJJ
VklMRUdFIl0sImp0aSI6ImE4MWZiYjExLWIxYTEtNDVmNy05ZTdjLTJiOTg5ZTkwMDliNCIsImNsaWV
udF9pZCI6ImxpdmUtdGVzdCIsInNjb3BlIjpbInNnLXNtYXJ0YXBwIl19.MwrPz4hCluQnG4kwLb2_gbZ4
fwk1ltWejQjo3OXavnk",
"t​ oken_type​": "bearer",
"r​ efresh_token​":
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiJpYnJhaGltLmF3bkBnbWFpbC5jb2
0iLCJzY29wZSI6WyJzZy1zbWFydGFwcCJdLCJhdGkiOiJhODFmYmIxMS1iMWExLTQ1ZjctOWU3Yy
0yYjk4OWU5MDA5YjQiLCJleHAiOjE1MDMzMzUzMjUsImF1dGhvcml0aWVzIjpbIlJFQURfUFJJVklM
RUdFIiwiV1JJVEVfUFJJVklMRUdFIl0sImp0aSI6ImNiNmY3NjNlLTdmY2QtNDJjYS04MDVlLTk4ZDR
mNGVjODU0NyIsImNsaWVudF9pZCI6ImxpdmUtdGVzdCJ9.fYXPxABiufiZLVMlTy2U2k5wuPUijrJEf0
efJdT8hkA",
"e ​ xpires_in"​ : 3599,
"s ​ cope"​ : "sg-smartapp",
"jti": "a81fbb11-b1a1-45f7-9e7c-2b989e9009b4"
}
400 Invalid ​USER_CREDENTIALS​ (Username and password entered by user is invalid)
{
"error": "invalid_grant",
"error_description": "Bad credentials"
}
401 Invalid ​CLIENT_CREDENTIALS

1.4. Refresh ACCESS_TOKEN

If the ACCESS_TOKEN is expired, then it can be renewed using REFRESH_TOKEN

Request
POST /oauth/token
Headers:
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64_CLIENT_CREDENTIALS
Form Data:
"Key":"grant_type", "value":"refresh_token"
"Key":"refresh_token", "value":"REFRESH_TOKEN"

Response
200 Returns ​ACCESS_TOKEN​ and ​REFRESH_TOKEN​ as below
{
"access_token":
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MDMyNTM2NTEsInVzZXJfbmFtZSI6Imlicm
FoaW0uYXduQGdtYWlsLmNvbSIsImF1dGhvcml0aWVzIjpbIlJFQURfUFJJVklMRUdFIiwiV1JJVEVfU
FJJVklMRUdFIl0sImp0aSI6Ijc1MzhjZmNjLTk4ZGUtNGNkMi04OGYwLWZjOTMyNWNjNjhkZCIsImNs
aWVudF9pZCI6ImxpdmUtdGVzdCIsInNjb3BlIjpbInNnLXNtYXJ0YXBwIl19.V4TNzj8tp0GKsOd03qoO
E7d-ihkmXmu8qUPcozVr6QQ",
"token_type": "bearer",
"refresh_token":
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiJpYnJhaGltLmF3bkBnbWFpbC5jb2
0iLCJzY29wZSI6WyJzZy1zbWFydGFwcCJdLCJhdGkiOiI3NTM4Y2ZjYy05OGRlLTRjZDItODhmMC1
mYzkzMjVjYzY4ZGQiLCJleHAiOjE1MDMzMzUzMjUsImF1dGhvcml0aWVzIjpbIlJFQURfUFJJVklMRU
dFIiwiV1JJVEVfUFJJVklMRUdFIl0sImp0aSI6ImNiNmY3NjNlLTdmY2QtNDJjYS04MDVlLTk4ZDRmN
GVjODU0NyIsImNsaWVudF9pZCI6ImxpdmUtdGVzdCJ9.sDntmUJH9UEPLJg6ZMQtAnaLI5lxj72QDX
FwurtzWxE",
"expires_in": 3599,
"scope": "sg-smartapp",
"jti": "7538cfcc-98de-4cd2-88f0-fc9325cc68dd"
}

401 Invalid ​ACCESS_TOKEN​ or C

​ LIENT_CREDENTIALS
1.5. Verify ACCESS_TOKEN
This API can be used to verify(usually while opening the app) to verify if ACCESS_TOKEN is still
valid. If ACCESS_TOKEN is expired, then app should try to get new ACCESS_TOKEN using
REFRESH_TOKEN (Check 4. Refresh ACCESS_TOKEN). If that also failed, then login page will be
shown to User.

Request
GET /oauth/check_token?token=​ACCESS_TOKEN
Headers:
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64_CLIENT_CREDENTIALS

Response
200 Username, Permissions (authorities) etc
{
"user_name": "email@example.com",
"scope": [
"sg-smartapp"
],
"active": true,
"exp": 1503253651,
"authorities": [
"READ_PRIVILEGE",
"WRITE_PRIVILEGE"
],
"jti": "7538cfcc-98de-4cd2-88f0-fc9325cc68dd",
"client_id": "live-test"
}

400​ ​ACCESS_TOKEN​ expired

{
"error": "invalid_token",
"error_description": "Token has expired"
}

1.6. Forgot Password

Request
PUT /api/forgot-password?email=​EMAIL_ID_OF_USER

Response
202 Request Accepted. This API returns only 202. If the email is valid and user available with that
email, then reset password token will be sent to that user.

1.7. Reset Password

 Property Type Constraints

token​* String Valid Token

password​* String New password,

confirm_password​* String Same as password

Request
PUT /api/reset-password
Headers:
Content-Type: application/json

{
"token": “UUID_SENT_ON_MAIL",
"password" : "123456",
"confirm_password": "123456"
}

Response
200 If Password updated successfully (No response JSON will be returned)
400 If Validation error occurs
{
"status": "BAD_REQUEST",
"message": "Validation Error",
"timestamp": "2017-08-26T19:21:01.873Z",
"errors": [
{
"field": "token",
"message": "Reset Token is required"
},
{
"field": "password",
"message": "Password is required."
},
{
"message": "Passwords do not match"
}
]
}