+1-757-461-3022 x124

Creating and Sharing API Keys for your xTupleCommerce Site

When implementing xTupleCommerce, there are several sets of API keys you need to create and retrieve to support our third-party integrations. These API keys give xTupleCommerce the ability to access and receive data from these third-party organizations (e.g., FedEx, Authorize.net, Google Maps). This is a very important part of creating a modern and useful web-based business application.

Example of How API Keys are used within xTupleCommerce

Using FedEx as an example, here is an outline of how API keys are used:

  1. Customer loads cart with products.
  2. Customer begins to check out.
  3. Customer enters shipping information.
  4. Customer progresses to the Shipping Option page of checkout.
  5. The xTupleCommerce site collects the shipping address, the address from which the products are shipping and the weight of the products in the cart and sends that data to FedEx via the API. It asks FedEx, "What are the available shipping options and their fees?"
  6. FedEx's system returns the available options and their associated fees to the xTupleCommerce site via the API.
  7. The xTupleCommerce site displays the returned data on the Shipping Options page .

This is simply one of many examples. As you can see, API keys are a very valuable asset to your xTupleCommerce site.

Current API Connections in xTupleCommerce

The API Connections that are currently available for xTupleCommerce are listed below.

What follows are instructions for retrieving those keys and safely sharing the information with your implementation team.

Authorize.net - Transaction API Keys

The following fields are required:

  • API Login ID
  • Transaction Key

Retrieving API keys from within Authorize.net

Here are the steps required to retrieve the Authorize.net keys:

  1. Go to Authorize.net.

  2. Log into your account as an admin.

  3. Click on “Account” in the main menu.

  4. In the Security Settings area click on API Login ID and Transaction Key.

[NOTE - every time you create an API Key the old Key expires within 24 hours. Your keys may be used in various locations (website, ERP, etc). Please save the keys in a secure location (LastPass.com, 1Password, etc) so you won’t have to recreate keys in the future.]

  1. Enter the answer to your account’s “Secret Question.”

  2. Click SUBMIT.

  3. Capture the keys.

  4. Deliver the keys to xTuple - follow the instructions below in the Sharing API Keys section.

UPS - API Keys

The following fields are required for both TEST and PRODUCTION environments:

  • UPS Account ID

  • UPS Access Key

  • UPS User ID

  • UPS Password

Retreiving UPS API Keys

Follow these steps to retrieve the UPS keys:

  1. Go to - UPS login.

  2. Log in with your account information.

  3. Click Support in the Main Menu.

  4. Inside the Browse By Topic box, click on UPS Developer Kit (screenshot).

  5. Inside the Access and Administration box, click Manage Access Keys (screenshot).

  6. Click Request New Access Key (screenshot).

  7. Follow the instructions.

  8. Capture the Keys.

  9. Deliver the keys to xTuple - follow the instructions below in the Sharing API Keys section.

[NOTE - Most systems delete old keys when new ones are created. Your keys could be used across multiple systems so it’s a very good idea to create these keys once and save the information in a safe place for future use. Our team uses systems like 1Password and LastPass for saving this information in a secure way.]

FedEx - API Keys

For FedEx, you will see that two different types of keys are needed: production keys and development keys. The first set are used in your production environment. The second set are used for testing and development.

Production Keys

For production keys, the following fields are required:

  • Account Username
  • Account Password
  • Authentication Key
  • Meter Number
  • Account Number
  • Production API Password
  • Production URL

Development Keys

For development keys, the following fields are required:

  • Account Username
  • Account Password
  • Test Key
  • Test Key Password
  • Test Account Number
  • Test Meter Number
  • Test URL

Obtaining FedEx API Keys

To obtain the needed keys from FedEx, follow these steps:

  1. Go to the FedEx Web Services Page.
  2. Login with your account.
  3. Click on the FedEx Web Services item in the left sidebar menu.
  4. Click on the Develop and Test link.
  5. Click the GET KEYS button.
  6. Double check all the information in the name and address fields. Then click continue.
  7. Accept the terms of service.
  8. The next page will include your keys. Copy all the details to a safe place.
  9. Click the CONTINUE button.
  10. Click the Move to Production link within the FedEx Web Services menu item in the left sidebar.
  11. Click the GET PRODUCTION KEY button.
  12. Answer the presented questions:
    • Do you intend to resell your software - No.
    • Please check the box next to each type of FedEx web services you intend to use in your integration solution - Check "FedEx Web Services for Shipping."
    • Please indicate whether you are developing your FedEx integration solution as a Corporate Developer or as a Consultant - Corporate Developer.
  13. Click Continue.
  14. Accept the terms of service.
  15. Ensure all fields are filled with correct info.
  16. Click Continue.
  17. If you updated information in the previous page you will be asked if you want to update your profile info. Check the box if you do and click continue. Otherwise skip to the next step.
  18. Copy your Authentication Key and Meter Number information to a safe place.
  19. Click continue to return to the home page.
  20. Check the email associated with your account.
  21. In the email you will find your password. Save that information to the same secure place.
  22. You now have everything you need to connect your xTupleCommerce site to your FedEx account.

USPS API Key (Address Validation)

The USPS key is simply used for address validation. This is not an API dey for USPS shipping services. Follow these steps to obtain the needed USPS key:

  1. Navigate to the USPS Web Tools page.
  2. Click the REGISTER NOW button.
  3. Fill out the form of required info and accept the terms of service.
  4. Click Register.
  5. After registering, the USPS will send you an email with the information required.

Google Maps API Key

If your organization uses Google Apps for email, Google Calendar, or Google Docs, simply go to one of these apps and log into your account. If needed, create a new free Google Account for your organization. We recommend using that one free account for all things related to Google.

  1. Once you are logged into your Google Account, you will need to setup API keys for the Google Maps API. To do that, go to the Google Maps Platform site - https://cloud.google.com/maps-platform/
  2. Click on the GET STARTED button.
  3. When prompted with, Enable Google Maps Platform options, choose the MapsRoutes and Places options and click Continue.
  4. Add a project name (perhaps the name of your website or organization) and click next.
  5. You will see a window saying “Enable Billing for project” - Note - this service is free up to a point, however payment info is required. As Google puts it, "No autocharge after free trial ends. We ask you for your credit card to make sure you are not a robot. You won’t be charged unless you manually upgrade to a paid account."
  6. Click Create Billing Account.
  7. Follow the instructions and add a credit card to the account.
  8. Submit your billing information.
  9. A new window will appear - Enable Google Maps Platform.
  10. Click Next.
  11. After a few seconds a new window will appear. This window is very important. It contains your API Key which is a long string of numbers and letters. Copy that entire key and save it to a safe place.
  12. Once you’ve saved the key to a safe place, close the window.
  13. You will be redirected to the Google Maps Platform Analytics Page. The Key you just saved is what you need for your xTupleCommerce project.
  14. On the Google Maps Platform Analytics Page, choose "APIs." Find the "Unused APIs" section and click on "Geocoding API" then ENABLE. Do the same for the "Geolocation API."

There are additional steps you can follow to continue configuring your Google Maps Platform, but that information is outside the scope of this article. Visit the Google Maps Platform Documentation to learn more.

Changing settings to an existing Google Maps API account

  1. Once you are logged into your Google Account, go to the Google Cloud Platform console - https://console.cloud.google.com
  2. Under Getting Started click on Explore and Enable APIs. Alternatively, click the menu in the top left corner and choose APIs & Services.
  3. Click on Library in the left side menu.
  4. Search for Geocoding API and select it from the results.
  5. Click Enable if the Geocoding API is not enabled yet or Click Manage if it is.
  6. Click APIs in the left side menu.
  7. Ensure the Geocoding API and Geocoding API are in the list of Enabled APIs. If not, click on them under the Additional APIs list and enable them. Then return to the API list by clicking APIs in the left side menu.
  8. Click on Geocoding API in the list of Enabled APIs.
  9. Click on the Credentials tab at the top of the page.
  10. If you do not have any API keys in the API Keys list, click the Credentials in the API Manager link to create a new API key.
  11. Click on your API key from the API Keys list.
  12. Ensure Application restrictions has None selected.
  13. Ensure API restrictions has Don't restrict key selected.
  14. Return to the API Keys list and copy the entire key and save it to a safe place.
  15. Next, ensure you have a Billing Account setup with Google. Click the menu in the top left corner and choose Billing.
  16. Make sure you have a credit card on file with Google on this page or add one.
  17. Close the Google Cloud Platform console window.

Restricting the API keys can be done at a later date after ensuring the API key is functioning on your xTupleCommerce website. Contact your implementor for further information on how to do that.

Google ReCaptcha Key

A recaptcha is a very common tool that is used to cut down on spam traffic. You are likely familiar with these tools. In some cases, they will ask you enter a string of text to prove you're not a robot. These tools are called captchas, and Google has built one they call a "ReCaptcha" (insinuating that they've made a better captcha).

Google's most recent recaptcha solution is simply a checkbox that say's "I'm Not a Robot" that the user must check to continue on. This is a major improvement in user experience, because it's simple but still blocks out the spammers. We understand that these tools may be seen as annoying, but they are very useful. They block web bots from creating spam accounts and/or logging into those spam accounts. Without this recaptcha gateway, your site could be the victim of dozens of spam account attempts per day. 

If your organization uses Google Apps for email, Google Calendar and Google Docs simply go to one of these apps and log into your account. If needed, create a new free Google Account for your organization. We recommend using that one free account for all things related to Google.

Before you can perform the following steps, be sure to ask your implementer for a list of domains you will need for setting up reCAPTCHA. These will be provided by xTuple.

  1. Once you are logged into your Google Account go to the Google ReCaptcha page.
  2. Choose the reCAPTCHA v2 option.
  3. In the domains section, enter all the domains that represent your site and your development sites. [Note: This may be 4 or so URLs.] Example, imagine your domain is example.com. You will likely have the following domains associated with your live website:
    • dev.example.xtuplecloud.com
    • pilot.example.xtuplecloud.com
    • live.example.xtuplecloud.com
    • example.com
  4. If you are unsure of your domains, reach out to your implementor for help.
  5. Click the "Accept the reCAPTCHA Terms of Service" box.
  6. Click Register.
  7. On the next page you will see the Keys section which includes your Site Key and your Secret Key. Copy these 2 keys into a safe place.
  8. Once you have saved those keys to a safe place you can paste them into your xTupleCommerce Control Panel and close the Google ReCaptcha window.

How to Securely Share API Keys (and other sensitive information)

It's important to consider these API keys as sensitive data which you should protect carefully. These keys are similar to your account and rounting number of your bank. They are not the kinds of data you want to simply email to other team members. Luckily, there are tools online that make it easy to share this data.

We suggest using LastPass.com to exchange sensitive information. This is a free online service that allows you to create “secure notes” then share access to those notes to other team members or with xTuple implementors. There are a lot of systems that exist, but from our experience, LastPass offers the most features for no cost. 

Creating and Sharing a Secure Note

  1. Go to LastPass.com.

  2. Login or Create an account.

  3. On your dashboard, rollover the red circle with plus sign in the lower right corner and click Create a Secure Note.

  4. Name the Note in this fashion - “year-month-day-CompanyName-Contents” (example - 2016-05-16-xTuple-APIKeys).

  5. Paste your keys (with labels) into the Notes field.

  6. Click Save.

  7. Hover over the recently created note, then click on the “Sharing” icon.

  8. Enter the email address of the account in which you are sharing the information and click "Share."

  9. This will send a notification email and will grant us access to the secure note.
up
103 users have voted.