Authorization Management

Overview

Hello and welcome! This guide will give you what you need to get started on integrating Basys' public endpoints into your solution. Once you have been onboarded into Basys' sandbox environment and have access to the IQPro Plus WebApp follow the steps below to create and manage your API integrations. If you have not been onboarded contact Basys support at (800) 386-0711or email: integrationsupport@basyspro.com.

How to Enable

To access Basys' APIs you must create an application within IQPro Plus. Through creating the application you are able to generate a corresponding client_id and secret_id. You will use these to generate an access token to access our APIs through our APIs page or through your desired API Platform.

Creating Applications and Secrets

Creating Secrets

To access the workflow to create an application log into IQPro Plus as a Gateway Admin under "Developer Hub" -> "Applications" -> "Create New"

Note: the Client ID that will be generated during this step will need to be specified in the POST body for the call that generates the access token

Create an application name and assign it a role. An application must be assigned the following roles with the corresponding permissions in order to generate secrets:

Creating and Managing Secrets

Once you have created an application you can generate up to two active secrets. Secrets are valid for 365 days and can be deleted at anytime.

To generate a secret for an application click the "+ Add Secret" in the Details View after an application has been created.

A secret must be named before it can be generated and can be copied from the Record Your Secret Modal! This secret can only be viewed and copied once!

Note: the secret_id that will be generated during this will need to be specified in the POST body for the call that generates the access token

NOTE: Securely store the client_id and secret_id in a database configuration file on your backend database. You will need to reference these GUIDs when generating access tokens. Basys reserves the right to disable any of these values or block service to an application altogether if there is wrongdoing suspected, even if the security of your application is compromised.

Deleting Application and Secrets

Applications can be deleted from the Application list view by clicking the "Delete Application" button. Deleting an application will delete all of the secrets that have been configured for the corresponding application

Secrets can deleted from the Details View by clicking the X under the actions column.

NOTE: Deleting applications and secrets will break any existing integrations leveraging them.

Generating Access Tokens

The values generated in the workflow above must be used to generate an access token to access our public APIs. To generate an access token make a POST call to the following URL:

https://account.basyspro.com/account.basyspro.com/B2C_1A_IQPROV2_INTEGRATOR/oauth2/v2.0/token

with an application/x-www-form-urlencoded body containing the following parameters:

grant_type=client_credentials
client_id=client_id
client_secret=secret_id
scope=https://account.basyspro.com/8939cd8f-0b21-4654-8f4d-ee01706dc3d6/.default

The endpoint will respond with a JSON response that looks like:

JSON Example

{
"access_token": "<string>",
"token_type": "Bearer",
"not_before": 1718830878,
"expires_in": 10080,
"expires_on": 1718840958,
"resource": "8939cd8f-0b21-4654-8f4d-ee01706dc3d6"
}

This access token can be used to make requests to your customer's account using an Authorization header like:

Authorization: Bearer <access_token_string>

Where <access_token_string> is your access token generated from the POST response

The not_before parameter is the time the access token will be valid

The expires_in parameter is the time (in seconds) until the access_token expires.

The expires_on parameter is the time the access token will be valid no longer be valid

NOTE: These access tokens expire after 168 minutes (10080 seconds) so you must make another call to the POST call mentioned about before the previous access toke expires and is no longer valid. To deliver highest level of security possible our access tokens align with OAuth2 authentication standards.

For more information on OAuth2 authentications and access tokens visit: https://oauth.net/2/

After you have generated your initial access token you will be able to retrieve applications as well as retrieve, create, and delete secrets through our APIs.

Making your first call to a Basys API

Congratulations! You are almost there. Now that you have your access token you can hit Basys APIs! You can do this one of two ways. Use our API Explorer; select the API you want to access from the list, click the "Try It >" button, input your access token as the authorization header, and click "Send" and you interact with our API from within the docs. Or use the following Base URL within the API collection that was provided during the onboarding process.

Base URL (Sandbox):

https://api.basyspro.com/iqsaas/v1/api

Headers

The following headers should be included with your requests:

Authorization

Calls to the API must include an Authorization header with the request. Specify the following authorization header:

Authorization: Bearer <access_token_string>

Content-Type

Content-Type should typically be set to application/json, unless you need to send your request body in a different format. All API responses will be in JSON format.

Programmatically Regenerating Secrets

Secrets are only valid for 365 days from the time they are created after this the secret will no longer be valid and are unable to create an access token. To prevent a scenario where your integration is broken due to being unable to generate an access token you must delete the old secret and create a new one before the old one expires. To do this perform the following steps:

1. Retrieve the application and secret details using the GET/gateway/{gatewayId}/appregistration/{appRegistrationId} endpoint

2. Securely store the application and secret details in a backend configuration file

3. Determine how far out you want to regenerate the secret based on the secrets endDateTime. We suggest updating it 14 days before it expires

4. If the secret is within this window make a call to the POST/gateway/{gatewayId}/appregistration/{appRegistrationId}/appsecret endpoint to generate a new secret. There is a restriction of 2 secrets per application so if there is more is 2 secrets configured for the application you may have to call the DELETE/gateway/{gatewayId}/appregistration/{appRegistrationId}/appsecret/{appSecretId} endpoint to delete a secret allow you to create a new one

5. Delete the secret that is getting ready to expire by calling the DELETE/gateway/{gatewayId}/appregistration/{appRegistrationId}/appsecret/{appSecretId} endpoint

6. Save the new secret details in the backend configuration file

We have the following C# code example of how you would make these calls to generate a new secret and delete the old one:

using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Json;
using System.Net.Http.Headers;
using System.Text.Json;
using System.Threading.Tasks;

namespace AppRegSample
{
   // Represents the application registration details.
   // This includes the app registration ID, the secret ID, and the secret's expiration datetime.
   public class AppRegistration
   {
       // Unique identifier for the app registration.
       public string AppRegistrationId { get; set; }
       // Unique identifier for the application secret.
       public string AppSecretId { get; set; }
       // Expiration date/time for the application secret (in UTC).
       public DateTime ExpirationDate { get; set; }
   }

   class Program
   {

       static async Task Main(string[] args)
       {
           // Set your gateway ID. Update this value with your actual gateway identifier.
           string gatewayId = "yourGatewayId";
           // Base URL for the API endpoints. Update this value as needed.
           string baseUrl = "https://sandbox.api.basyspro.com/iqsaas/v1/api/";
           // Retrieve and Set your bearer token for authorization.
           string bearerToken = "yourBearerToken";
           // Local file to simulate storing configuration or database details. Note in production this should be store in a secure location.
           string configFilePath = "AppRegistration.json";


           using HttpClient client = new HttpClient { BaseAddress = new Uri(baseUrl) };
           client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", bearerToken);

           AppRegistration appRegistration = null;
           // Load stored registration data if available; otherwise, retrieve from the GET endpoint.
           if (File.Exists(configFilePath))
           {
               appRegistration = LoadAppRegistration(configFilePath);
               Console.WriteLine("Loaded stored app registration.");
           }
           else
           {
               appRegistration = await GetAppRegistrationAsync(client, gatewayId);
               SaveAppRegistration(configFilePath, appRegistration);
               Console.WriteLine("Retrieved and stored new app registration.");
           }

           // Check if the current secret is near expiration (e.g., within 14 days).
           if ((appRegistration.ExpirationDate - DateTime.UtcNow).TotalDays < 14)
           {
               Console.WriteLine("Secret is near expiration. Creating new secret...");

               // Call the POST endpoint to create a new secret.
               AppRegistration newSecret = await CreateNewSecretAsync(client, gatewayId, appRegistration.AppRegistrationId);

               // Call the DELETE endpoint to delete the old secret.
               Console.WriteLine("Deleting old secret...");
               await DeleteSecretAsync(client, gatewayId, appRegistration.AppRegistrationId, appRegistration.AppSecretId);

               // Update the stored registration with the new secret details.
               appRegistration.AppSecretId = newSecret.AppSecretId;
               appRegistration.ExpirationDate = newSecret.ExpirationDate;
               SaveAppRegistration(configFilePath, appRegistration);
               Console.WriteLine("Updated app registration with new secret.");
           }
           else
           {
               Console.WriteLine("Secret is still valid. No update needed.");
           }
       }

       /// <summary>
       /// Calls the GET endpoint to retrieve the application registration details.
       /// </summary>
       /// <param name="client">HttpClient instance to use for the API call.</param>
       /// <param name="gatewayId">The gateway identifier to be inserted into the URL.</param>
       /// <returns>An AppRegistration object populated with the API response.</returns>
       static async Task<AppRegistration> GetAppRegistrationAsync(HttpClient client, string gatewayId)
       {
           // Build the endpoint URL.
           string endpoint = $"gateway/{gatewayId}/appregistration";
           HttpResponseMessage response = await client.GetAsync(endpoint);
           response.EnsureSuccessStatusCode();

           // Deserialize the JSON response into an AppRegistration object.
           AppRegistration registration = await response.Content.ReadFromJsonAsync<AppRegistration>();
           return registration;
       }

       /// <summary>
       /// Calls the POST endpoint to create a new application secret.
       /// </summary>
       /// <param name="client">HttpClient instance to use for the API call.</param>
       /// <param name="gatewayId">The gateway identifier to be inserted into the URL.</param>
       /// <param name="appRegistrationId">The app registration identifier.</param>
       /// <returns>An AppRegistration object containing the new secret details.</returns>
       static async Task<AppRegistration> CreateNewSecretAsync(HttpClient client, string gatewayId, string appRegistrationId)
       {
           // Build the endpoint URL.
           string endpoint = $"gateway/{gatewayId}/appregistration/{appRegistrationId}/appsecret";
           // Send an empty POST request. Adjust if your API requires a request body.
           HttpResponseMessage response = await client.PostAsync(endpoint, null);
           response.EnsureSuccessStatusCode();

           // Deserialize the response containing the new secret details.
           AppRegistration newSecret = await response.Content.ReadFromJsonAsync<AppRegistration>();
           return newSecret;
       }

       /// <summary>
       /// Calls the DELETE endpoint to remove the old application secret.
       /// </summary>
       /// <param name="client">HttpClient instance to use for the API call.</param>
       /// <param name="gatewayId">The gateway identifier to be inserted into the URL.</param>
       /// <param name="appRegistrationId">The app registration identifier.</param>
       /// <param name="appSecretId">The application secret identifier to delete.</param>
       static async Task DeleteSecretAsync(HttpClient client, string gatewayId, string appRegistrationId, string appSecretId)
       {
           // Build the endpoint URL.
           string endpoint = $"gateway/{gatewayId}/appregistration/{appRegistrationId}/appsecret/{appSecretId}";
           HttpResponseMessage response = await client.DeleteAsync(endpoint);
           response.EnsureSuccessStatusCode();
       }

       /// <summary>
       /// Saves the AppRegistration object to a file as JSON.
       /// This simulates storing the registration details in a backend database or configuration file.
       /// </summary>
       /// <param name="filePath">The path to the file where the JSON will be saved.</param>
       /// <param name="registration">The AppRegistration object to save.</param>
       static void SaveAppRegistration(string filePath, AppRegistration registration)
       {
           // Serialize the object to JSON with indented formatting for readability.
           string json = JsonSerializer.Serialize(registration, new JsonSerializerOptions { WriteIndented = true });
           File.WriteAllText(filePath, json);
       }

       /// <summary>
       /// Loads the AppRegistration object from a JSON file.
       /// </summary>
       /// <param name="filePath">The path to the file containing the JSON.</param>
       /// <returns>The deserialized AppRegistration object.</returns>
       static AppRegistration LoadAppRegistration(string filePath)
       {
           string json = File.ReadAllText(filePath);
           AppRegistration registration = JsonSerializer.Deserialize<AppRegistration>(json);
           return registration;
       }
   }
}