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.

🚧

Using OAuth 2.0 authentication, assume that you already have an app on inTandem platform that you need to authenticate with your users.
If you don't have an app yet, you can create one following the instructions in this guide.

Upon creating your app on inTandem platform you received a client id and secrete 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 he 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 chained to it. The redirect URL will look as follows:

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

📘

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!

$STATE is the value passed via the authorization URL

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

https://api2.vcita.com/oauth/token

Payload:

• 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.
• grant_type - should be 'authorization_code'

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 can be later used as an authorization token in API requests:

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

Using 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 how the access token is used. In this case, we will request the business' user info:

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