New Public API Enhancement: Customer Action Required by the end of March 2024

By the end of March 2024, a mandatory update for all customers using Turvo's Public API will require generation of a new API key and using new URLs. This update is designed to provide enhanced security and improved API call management.

All Turvo integrations using the Public API will be also impacted by this enhancement.

Important note: REST API calls (GET, PUT, POST, and DELETE, for example) will not be impacted if you generate a new API key by the end of March 2024. However, if you have not completed the following steps by the end of March, you will no longer be able to access the legacy Turvo Public API which will result in API downtime.  

Steps necessary to enable the API enhancement

Complete the following steps by the end of March 2024 to ensure the API enhancement update is successful. Steps 3 and 5 are especially critical for you to complete to avoid any API issues:

  1. Note the new API server address changes
  2. Create users for API profiles (if necessary)
  3. Create your new API keys
  4. Create your Public API profiles (if necessary)
  5. Use the new API key as a header attribute to make Public API calls and Generate Auth Tokens using the new API gateway key

1.  Note the API server address changes

With this update, note that our Public API server addresses are changing:

Production

  • Old URL:  https://app.turvo.com/api/pub
  • New URL:  https://publicapi.turvo.com/v1

Test (Sandbox)

  • Old URL:  https://my-sandbox.turvo.com/api/pub
  • New URL:  https://my-sandbox-publicapi.turvo.com/v1

2. Create users for API profiles (optional if you already have users for API profiles)

Before you can create an API profile, you must create an Admin-level user that will be associated with it. This username will appear in the shipment or order timelines whenever a change is made to the entity by that specific integration. Therefore, it is important to create a special Admin user for these profiles rather than using a real person’s username.

Important note: Only Super Admins can create and manage public API and Webhook profiles. Users with Admin-level permissions and above can view the information available on the Configuring Public API page.

To learn how to create a user, see How to create and manage users.

We recommend using the name of the system you are integrating with as the name of the user. For instance, if you are creating an API profile for a CRM integration, name the user “CRM Integration.”

Important note: Email addresses associated with users in Turvo must be valid email addresses. Passwords are required for API authentications and, if needed, password generation links are sent to the email associated with the user. This means that your organization may need to create email addresses that correspond to the admin users needed for API profiles.

Accessing the Public API and Webhooks page

Login to your Turvo tenant and click the Profile icon at the top right of the page, and select Admin console from the drop-down menu to create public API profiles, webhook profiles, manage your API keys, or access public API documentation.

image-0.png

Then, click the API & Webhooks card.

Updated_Admin_API_and_Webhooks.png

3. Create New API keys

If this is the first time you are generating an API key, you will see the following screen. To create an API key for your tenant, click + Add api key.

Screenshot 2023-09-18 at 4.20.44 PM.png

If you have previously generated API keys, you will see the following screen. Click ADD NEW KEY to generate a new API key. If you have reached your limit for API keys, the letters will be greyed out. 

2023-09-12_17-35-54.png

The screen refreshes with an automatically generated API key. The auto-generated  API key will be the name of your tenant and a randomly generated combination of alpha-numeric characters.

add new key_public API and webhooks.png

Editing API key names

You can give your keys unique names to help  recognize the keys being used and appropriately connect them to other systems.

To edit the names of your API keys, click the Edit icon to the right of the API key name field.

add new key_change name.png

Then, enter the desired name for your key and click the check mark to save your changes.

add new key_rename_checkmark.png

Refreshing and copying keys

Users also have the ability to manually refresh their key without having to  contact Turvo support. However, it’s  keys can only be updated once a week. To refresh the API key, click the circular arrow icon to the right of the key.

new api key_refresh.png

Also, if you need to copy the key for any reason, you can click the copy icon immediately to the right of the refresh icon.

add new key_refresh.png

Clicking the icon will automatically copy the key to your computer’s clipboard, so you can easily paste it where it’s needed.

Viewing Last updated details and API Call rate limit per unit time

Users can view the details of when the API key was last updated and the Call rate limit per unit time below the API Key.

add new key_call rate_num of keys.png

 

4. Create Public API profiles (optional if you already have API profiles)

Turvo’s Public API provides you with the ability to integrate with Turvo through RESTful methods. Our API has predictable, resource-oriented URLs, uses HTTP response codes to indicate API errors, and all requests and responses are in JSON format.

  1. On the Configuring Public API page, make sure you’re on the Public API Profile tab and click + Add public API profile.

    Add public API Profie.png

  2. Next, fill in the information available in the Create public API profile modal:

  3. When all fields are completed, the SAVE button will change from grey to blue and you can click SAVE to save your changes.

5. Use the new API key as a header attribute to make Public API calls

Use the API key that is generated in the Admin console in API key (x-api-key) as a header attribute Turvo Public API calls:
'x-api-key: <API Key generated in the Admin console>'

You can test to see if you successfully implemented the new enhancement by making a sample successfully API call like the generation of Auth tokens step below using the new API gateway key. 

Generate Auth Tokens using the new API gateway key

Generate the Auth Token using the API gateway key by filling in the highlighted text in the code block below and initiating the request:

{
curl -- location -- request POST
'https://publicapi.turvo.com/v1/oauth/token?client_id=publicapi&client_secret=secret' \ --header 'x-api-key: API key generated in Admin console, \ --header 'Content-Type: application/json' \ --data-raw '{ "grant_type":"password", "username": username, "password": password, "type":"business", "scope":"read+write+trust" }'


View a list of users with the new API gateway key

To create and view a list of all the users in your organization that are using a new API key and have completed the necessary steps to use this enhancement, first complete the previous step, then initiate this request:

{
  curl --location --request GET 'https://publicapi.turvo.com/v1/users/list' \
--header 'x-api-key: API key generated in Admin console,'
--header 'Authorization: Bearer access_token value generated in the previous step'
}'


Editing and Deleting API profiles and Managing Webhook profiles

For more information on editing and deleting API profiles and managing your webhook profiles see Using Turvo's self-service Public API and Webhooks.

Was this article helpful?

0 out of 0 found this helpful