OAuth 2.0 authorization Flow

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

🚧

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

Step 1: Get your app's client id and client secrete ready

Upon creating your app on vcita 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

vcita's authorization URL:

https://app.vcita.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 log in first.

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 that was a pass to vcita in 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 from vcita after the user granted access.
• client_id - Use the unique identifier you received when you registered your application with vcita (step 1).
• client_secret - Use the Secret value you received when you registered your application with vcita (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's 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}}' \