OAuth 2.0 authorization Flow

You can use OAuth 2.0 to authenticate all your application's API requests to inTandem platform. OAuth provides a secure way for your application to access our data on behalf of the authorized business.

🚧

Use OAuth 2.0 authentication to authenticate your app on inTandem platform with your users. If you don't have an app within our platform, you can create one following the instructions in this guide.

Upon creating your app on inTandem platform you received a client id and secret id in the API response. Make sure you have those ready, as they'll be required in the next steps.

Authorization URL:

https://HOST_DOMAIN.com/app/oauth/authorize?client_id=$CLIENT_ID&redirect_uri=$REDIRECT_URI&state=$STATE

$STATE is an arbitrary string that will be appended to the callback URL after the Authorization step is complete

If the user is not currently logged in they will be prompted to login first. Example of vcita default login page:

At that point, depending on whether your app is configured as Trusted or not, the user will be prompted with a permission grant dialog where approval is required in order for the OAuth flow to continue.

Once the user authorizes the app, the user will then be redirected to the configured app redirect_uri, with additional parameters sent in the url. The redirect URL will show as follows:

$REDIRECT_URI?code=$CODE&state=$STATE

$STATE is the value passed via the authorization URL

📘

code

The code value is a temporary Authorization Code that can be exchanged for an Access Token.

Note: the code will remain valid for only 30 seconds!

To get the access token, you need to send a POST request to the following endpoint:

https://api.vcita.biz/oauth/token

Payload:

• grant_type - should be 'authorization_code'
• code - use the authorization code you received in the response after the user granted access
• client_id - use the unique identifier you received when you registered your application with inTandem (step 1)
• client_secret - use the Secret value you received when you registered your application with inTandem (step 1)
• redirect_uri - the same redirect URL as in step 2. For ID purposes only.

curl https://api.vcita.biz/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "authorization_code", "code": "{your_code}",
    "client_id": "{your_client_id}", "client_secret": "{your_client_secret}", 
    "redirect_uri": "{your_redirect_url}" }' \
  -X POST

The response will include the access token that you can later use as an authorization token in API requests:

Status: 200 OK
 
{
"access_token": "74639aa91e5726dc4d90ca82621aeebe028923bde08e1715cf8809178c7f144b",
"token_type": "bearer",
"expires_in": 631152000,
"created_at": 1565876581,
}

With the access token your app can make API calls on behalf of the authorized business, by including the token in an HTTP Authorization header.

'Authorization: Bearer {{access_token}}'.

Here is an example of using the access token. In this case, we request for the business' user info:

curl --request GET \
     --url https://api.vcita.biz/oauth/userinfo \
     --header 'Accept: application/json'
     --header 'Authorization: Bearer {{access_token}}' \