New Public API Enhancement: Customer Action Required by November 30, 2023

On November 30, 2023, a mandatory update for all customers using Turvo's Public API will require generation of a new API key and using a new URL. 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.

On September 18, 2023, we released the Public API enhancement to all customers so that you can enable this enhancement before November 30, 2023. By November 30, or if you want to use the enhancement earlier, you will need to follow the steps in this article to generate a new API key and update the URL to use the Turvo Public API. 

Note: REST API calls (GET, PUT, POST, and DELETE, for example) will not be impacted if you generate a new API key by November 30.

The following steps need to be completed to complete access to this enhancement:

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
6. Generate Auth Tokens using the new API gateway key

API server address changes

With this update, 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

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.

Creating 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.

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.

Then, click the API & Webhooks card.

Creating API keys

Important note: This feature may not be available in your tenant. Contact your Turvo representative if you need help enabling the API Key management features.

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.

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. 

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.

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.

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

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.

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.

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.

For information on accessing API documentation, see the How to access Turvo Public API & Webhooks documentation Help Center article.

Creating public 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.
   
   
   
   

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.
   
   

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

You must follow the step below to generate 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>'

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"
}'

Viewing 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.