OAuth 2.0 Authentication Flow

Using OAuth 2.0 authentication with your application

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 without having to store and use the passwords of vcita users, which is sensitive information.
To use OAuth 2.0 authentication, you need to register your application first (read more under the 'application lifecycle section'). You also need to add some functionality to your application to support the OAuth authorization flow.

Step 1: Registering your application

Please skip this step if the application already registered and has **Clinet ID** and **Client Secret**

You must register your application to generate OAuth credentials, that your application can use to authenticate API calls to vcita.

To register your application:
Send a request Here with the following details

  • App Name - Enter a name for your app. This is the name that users will see when asked to grant access to your application, and when they check the list of third-party apps that have access to their vcita.
  • Description - Optional. This is a short description of your app that users will see when asked to grant access to it.
  • Logo - Optional. This is the logo that users will see when asked to grant access to your application. The image can be a JPG, GIF, or PNG. For best results, upload a square image.
  • Redirect URL - Enter the URL that vcita should use to send the user's decision to grant access to your application. The URLs must be absolute and not relative, only valid URL and https.

Once reviewed vcita will provide the following information back to the App Developer:

  • Client ID
  • Client Secret
    These values will be used by the App developer during the authorization flow

Step 2: Redirect User to the Authorization URL

Your application has to send the user to the vcita authorization page. The page asks the user to authorize your application to access vcita on their behalf. After the user makes a choice, vcita sends the choice and a few other bits of information back to your application.

The format for the URL looks as follows:

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

  • $CLIENT_ID should be replaced by the Client ID the developer received at the end of Step 1.
  • $REDIRECT_URI should be the redirect URI specified when the App was created in Step 1.
  • $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 before continuing the flow.

The User will then arrive at the Authorization screen where they will be prompted to authorize the App.
Once the User authorizes the App the User will then be redirected to the callback URL with several additional parameters. The redirect URL will look as follows:

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

  • $CODE is a temporary Authorization Code that can be exchanged for an Access Token
  • $STATE is the value that was a pass to vcita in the authorization URL

Step 3: Exchange Code for Access Token

If your application received an authorization code from vcita in response to the user granting access, your application can exchange it for an access token. To get the access token, make a POST request to the following endpoint:
https://api2.vcita.com/oauth/token

Include the following required parameters in the request:

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 example:

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

Example response

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

Step 4: Use the access token in API calls

The app can use the access token to make API calls. Include the token in an HTTP Authorization header with the request. as follows:

Authorization: Bearer {a_valid_access_token}

For example, a cURL request to get information about the token you received would look as follows:

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

And the response should look like:

{
  "business_id": "123456789",
  "email": "[email protected]",
  "role": "owner",
  "sub": "987654321"
}

Did this page help you?