OAuth 2.0 authorization Flow
Authenticate and generate an API access token for your apps
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.
Step 1: Get your app's client id and client secret ready
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.
Step 2: Redirect users to the Authorization URL
Authorization URL:
$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
Step 3: Exchange Code for Access Token
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,
}
Step 4: Use the access token in API calls
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}}' \
Updated about 2 months ago