Customer Data Validation plays a critical role in our API sales model. We strongly believe in the principle that “seeing is believing,” and we encourage potential customers to try out our APIs before making a purchase. To facilitate this, we provide trial keys to prospective customers who can then utilize our integration guides to implement our API in a test environment and validate their customer data. Our staff is available to assist and guide them through the process, ensuring that their customer data is accurately validated.
When customers are ready to transition from their test environments to production environments, they often ask, “What do we need to do to go live?” The answer varies depending on the API access being purchased. Different considerations arise based on the API type and the corresponding key system that governs it. Our API access is governed by various systems, including Traditional License Keys, Custom Keys, and AuthIDs. In this blog, we will delve into the specific factors to consider for each key type when migrating to the production environment.
To begin, you can identify the type of key that governs your API access by examining the key format. Traditional keys typically start with “WS,” custom keys consist of 32-digit alphanumeric values, and AuthIDs are composed of 36-digit alphanumeric values with hyphens.
Traditional Keys
Traditional keys are commonly used in our API services to grant access. Both the trial and production versions of these keys function in the same way but are meant for different environments. When transitioning to a production environment, there are two main elements that need to be updated: the endpoints and the license keys.
Trial endpoints are straightforward, starting with “trial.serviceobjects.com” followed by the path to the specific service and operation being targeted. To switch the endpoint to the production environment, it’s as simple as changing “trial” to “sws,” like this: “sws.serviceobjects.com.” If you want to implement failover, which is a recommended best practice for ensuring high uptime and availability, you should update your failover endpoint to “swsbackup.serviceobjects.com.”
The next step is updating the license key. Simply replace the license key used for testing with the one you have purchased. If you’re unsure about which key to use, you can reach out to us, and we’ll be happy to help you identify the correct one.
After these changes are made it is important to test your implementation to make sure everything was set correctly.
Though it isn’t a complex topic, to switch from trial to production, we have made it even simpler with coding libraries that we have been working on. A couple of changes would still be required like updating your license key, but if you use one of our prebuilt libraries, you’ll just need to switch a variable from trail to live and you’re all set. The beauty of the libraries is that they also take care of best practices, including Customer Data Validation and failover implementation. You don’t need to worry about writing all the code yourself; simply include one of our libraries in your project, pass your license key, and indicate the trail/production status through a Boolean flag, and you’re good to go.
One important aspect to note regarding Traditional License Keys is to ensure that they are not used directly in JavaScript scenarios. In Javascript, it is relatively easy for the general public to access your web page, obtain your key, and use it for their own purposes. Therefore, it is vital to avoid listing your license key in JavaScript code, which helps maintain the integrity of your Customer Data Validation.
Custom Keys
Custom keys were implemented in response to the need for a license key to reside in Javascript for our DOTS Global Address Complete service. Global Address Complete is a front-end web tool that converts a textbox to an address type ahead or address suggestion field and is our only service to use Custom keys. Multiple Custom Keys can be generated for our customers who want to use the service in multiple solutions. Much of the Global Address Complete functionality is supported by Javascript code, and calls to the backend API are made from it. To make the calls to the API more secure, we established Custom Keys, which can be locked down to specific domains. This means if someone snoops the Custom Key and you have it locked down to your domain, it will not be able to be used in other web apps.
Now, let’s discuss the process of transitioning from a trial Custom key to a production Custom key. Similar to other key types, it is crucial to replace the trial Custom key with a production Custom key. It is important to ensure that the correct keys are in the appropriate locations and to double-check their proper usage. Often, customers utilize an unrestricted key during the development phase for ease of development. However, it is necessary to update the production version of the key to maintain security. Both trial and production Custom keys can have domain restrictions applied to them. Therefore, when moving to the production environment, it is vital to verify that the correct restrictions are applied to the respective key. If you have any questions regarding this process, please reach out to us, and we can review the restrictions and keys to ensure a successful transition to production.
When reviewing the developer guides on how to implement Global Address Complete, you’ll notice that a couple of reference links should be updated too. First, in the head tag, the link to the trial version of the css should be switched from trial to sws, for example:
trial.serviceobjects.com/Resources/AC/CSS/ACStyle.css
should be
sws.serviceobjects.com/Resources/AC/CSS/ACStyle.css
Similarly, the second part to update is the script to include the js helper file. The script tag should also switch from trial to sws like this:
trial.serviceobjects.com/Resources/AC/JS/ACScriptV1.02.js
should be
sws.serviceobjects.com/Resources/AC/JS/ACScriptV1.02.js
If this is not switched, you won’t notice a difference. However, it is important to note that both of these files, particularly the JavaScript file, handle traffic redirection to the correct environments. Using the trial version puts your solution at risk of becoming unavailable during maintenance or other development activities in the trial environment. Making sure you switch to sws, the production environment will ensure five 9’s of availability.
Another aspect that requires adjustment when transitioning to production is the options. When setting up Global Address Complete there is a Javascript piece of settings code you embed in your page that governs how the Global Address Complete service will function. Custom Key and an option for setting an isTrial variable are among the settings. It defaults to true, so if you do not see this option, you can assume you have isTrial set to true. In this section of code, you’ll either want to add isTrail: false or simply switch the value from true to false depending on your setup. More details about what to expect in this area can be reviewed on our dev guides for Global Address Complete or more specifically the Javascript Options section.
AuthIDs
AuthIDs are our latest key type. They are more like our Traditional License keys but offer more security based on their size and character variation. Again, do not use AuthIDs or Traditional keys in Javascript. When moving to production with these AuthIDs, you’ll need to switch from a trial AuthID to a production AuthID as well. Again, if you’re unsure which AuthID is which please reach out and we’ll help you immediately. Besides swapping out the AuthID, you’ll also need to switch endpoints from trial to production. The trial endpoint is the same as the other keys and the base is trial.serviceobjects.com. But production is a little bit different; the endpoint to switch to is sws.serviceobjects.com and the production backup endpoint is swsbackup.serviceobjects.com. Always do implement failover, which you can achieve by either writing the code yourself, using our sample code, or using one of the code libraries we have written that rolls all of that stuff up for you. Instead of writing all the code, simply include one of the libraries in your project and pass your license key and a trial/production Boolean flag, and you are set. A future goal of these AuthIDs is to allow for rotating in and out, on a periodic schedule, new AuthIDs to add to the security of the system.
In summary, API access to our services has evolved over the years, and in any case, access to the APIs we sell is easily maintained as you move your project from development to production. As you migrate your integration, you’ll need to make a couple of simple changes as you to your project.
