OAuth Workflow

Exchange authorization code for access token

Once the user has finished their onboarding, the Synaps Client triggers an event called userOnboardSuccess with an authorization code.

SynapsClient.on('userOnboardSuccess', (code) => {
// Exchange {code} for access token
});

You are then able to exchange this code for an access_token. This access token allows you to make requests to the API on the behalf of a user.

get
Request Access Token

https://connect.synaps.io/v1/oauth/token
Return access tokens and user info
Request
Response
Headers
Authorization
required
string
Your app client_id and client_secret separated by colon Example S1119345501234566:PD2rzu3QYUkenwEf8ua6w7ENCrBs
Content-Type
optional
string
application/json
Query Parameters
code
required
string
Authorization code Example : ygVeEzgVnFvSUhKCWj2nNdvq6Erv
grant_type
required
string
Authorization grant type Example : authorization_code
200: OK
Valid access token request
{
"data": {
"user_unique_identifier": "12526490623501658",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiIyIiwiZXhwIjoxNTQ1MzU4MjE5LCJpYXQiOjE1NDUyNzE4MTksImlzcyI6InN5bmFwcy1jb25uZWN0LWFwaSIsInVzZXJfaWQiOiIyIn0.iIudOhZfy6MQnzKX0xduyvVzeajbDu7-6EF7-Z8qnTI",
"token_type": "bearer",
"expires_at": 1545358219,
"refresh_token": "LIhZWY7pHfuZ6YP7ptVcErUbs2hHwq7EbQGGxcg2CQ1g36el8IrTLXIxxIMspcNt"
},
"status": {
"error": false,
"api_code": "SUCCESS",
"type": "success",
"message": "success"
}
}
400: Bad Request
Invalid authorization code
{
"data": null,
"status": {
"error": true,
"api_code": "INVALID_AUTHORIZATION_CODE",
"type": "error",
"message": "Invalid authorization code"
}
}

API Response

Field

Type

Description

user_unique_identifier

string

Unique User ID to identity your app user

access_token

string

Access token to access user resources

token_type

string

Access token type

expires_at

number

Access token expiration in timestamp

refresh_token

string

Token needed to refresh user access_token

The access token lasts 24 hours. You have to use the refresh token to request a new access token when it expires.

Code Snippets

Refresh access token

An access token last 24 hours. To keep making requests you have to refresh the access token using the refresh token given during the authorization workflow.

get
Refresh access token

https://connect.synaps.io/v1/oauth/token
Return new access token
Request
Response
Headers
Authorization
required
string
Your app client_id and client_secret separated by colon Example S1119345501234566:PD2rzu3QYUkenwEf8ua6w7ENCrBs
Query Parameters
refresh_token
required
string
User refresh token Example : LIhZWY7pHfuZ6YP7ptVcE...
grant_type
required
string
Refresh grant type Example : refresh_token
200: OK
Valid refresh token
{
"data": {
"user_unique_identifier": "12526490623501658",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiIyIiwiZXhwIjoxNTQ1MzU4MjE5LCJpYXQiOjE1NDUyNzE4MTksImlzcyI6InN5bmFwcy1jb25uZWN0LWFwaSIsInVzZXJfaWQiOiIyIn0.iIudOhZfy6MQnzKX0xduyvVzeajbDu7-6EF7-Z8qnTI",
"token_type": "bearer",
"expires_at": 1545358219,
"refresh_token": "LIhZWY7pHfuZ6YP7ptVcErUbs2hHwq7EbQGGxcg2CQ1g36el8IrTLXIxxIMspcNt"
},
"status": {
"error": false,
"api_code": "SUCCESS",
"type": "success",
"message": "success"
}
}
400: Bad Request
Invalid refresh token
{
"data": null,
"status": {
"error": true,
"api_code": "INVALID_REFRESH_TOKEN",
"type": "error",
"message": "Invalid refresh token"
}
}

API Response

Field

Type

Description

user_unique_identifier

string

Unique User ID to identity your app user

access_token

string

Access token to access user resources

token_type

string

Access token type

expires_at

number

Access token expiration in timestamp

refresh_token

string

Token needed to refresh user access_token

The refresh token doesn't expire. It becomes inactive when the user revokes your app access

Token introspection

Token introspection gives you some information about an access token.

post
Get access token info

https://connect.synaps.io/v1/oauth/token_info
Return access token information
Request
Response
Headers
Authorization
required
string
Your app client_id and client_secret separated by colon Example S1119345501234566:PD2rzu3QYUkenwEf8ua6w7ENCrBs
Content-Type
optional
string
application/json
Query Parameters
token
required
string
Access token Example : eyJhbGciOiJIUzI1...
200: OK
Valid access token
{
"data": {
"active": true,
"scope": "email phone identity residency",
"client_id": "S1119345501234566",
"user_unique_identifier": "12526490623501658",
"expires_at": 1545359102
},
"status": {
"error": false,
"api_code": "SUCCESS",
"type": "success",
"message": "success"
}
}
400: Bad Request
Invalid access token
{
"data": null,
"status": {
"error": true,
"api_code": "INVALID_ACCESS_TOKEN",
"type": "error",
"message": "Invalid access token"
}
}

API Response

Field

Type

Description

active

boolean

Token state

scope

string

Space-delimited authorized scopes

client_id

string

Owner of the access token

user_unique_identifier

string

User linked with this access token

expires_at

number

Token expiration in timestamp