Authorization Guide

Getting Started

Obtaining an API Key

VBASoftware APIs support both test and live environments. The API key used to authenticate a request determines whether it operates in test mode or production mode.

API keys grant significant privileges, so it is essential to keep them secure. Do not expose your secret API keys in public repositories, client-side code, or any publicly accessible location.

To request an API key, please contact your Account Executive.

Acquiring an API Client

The easiest way to integrate with VBASoftware APIs is by using one of our pre-generated client libraries. These SDKs are built following the OpenAPI specification to ensure seamless interaction with our APIs.

Web-based npm Clients

Our JavaScript/TypeScript client is available via npm and can be installed with:

Copy
Copied
npm install @vbasoftware/vbapi-vbasoftware-typescript-axios

Local Clients

For other languages, we provide downloadable client libraries:

Build Your Own Client (BYOC)

You can generate a custom API client in over 50 programming languages using the OpenAPI Generator.

Authentication & API Access

Logging into the API

All API requests require authentication with a valid VBASoftware user account. You can create a user account using the Create User API or request assistance from a VBASoftware administrator.

The following C# code snippet demonstrates how to authenticate a user and obtain an id-token for use in subsequent API requests.

User Authentication Request (C#)

Copy
Copied
using Newtonsoft.Json.Linq;
using RestSharp;

private string Get_Id_Token()
{
    var client = new RestClient("https://vbapi.vbasoftware.com/vbasoftware/");
    var request = new RestRequest("/user-authentication", Method.POST);

    request.AddHeader("x-api-key", {your_api_key});
    request.AddHeader("Authorization", $"Basic {base64_encoded_username_and_password}");
    request.AddHeader("vbasoftware-client-id", {your_client_id});
    request.AddHeader("vbasoftware-client-code", {your_client_code});
    request.AddHeader("vbasoftware-database", {your_desired_database});

    var response = client.Execute(request);
    var jsonResponse = JObject.Parse(response.Content);
    JObject dataJson = (JObject)jsonResponse.GetValue("data");
    JObject authenticationResultJson = (JObject)dataJson.GetValue("authenticationResult");
    
    return (string)authenticationResultJson.GetValue("idToken");
}

Making an Authenticated Request

Once authenticated, you can use the obtained id-token to make authorized API requests. The following example retrieves a specific benefit by passing the id-token in the Authorization header as a Bearer token.

Retrieve a Benefit (C#)

Copy
Copied
string idToken = Get_Id_Token();
RestRequest getRequest = new RestRequest($"/benefits/{Benefit_Code}", Method.GET);

getRequest.AddHeader("x-api-key", {your_api_key});
getRequest.AddHeader("Authorization", $"Bearer {idToken}");
getRequest.AddHeader("vbasoftware-database", {your_desired_database});

IRestResponse response = httpClient.Execute(getRequest);
var getJsonResponse = JObject.Parse(response.Content);
JObject getDataJson = (JObject)getJsonResponse.GetValue("data");
BenefitCodes benefitCode = getDataJson.ToObject<BenefitCodes>();

For additional details on API response formats, refer to the Response Handling Documentation.

By following this guide, you can successfully authenticate and interact with VBASoftware APIs using secure best practices.