Just as Traffio integrates with various external applications for invoicing, payroll, and other functions, external applications can also integrate with Traffio using the third-party API.
Before an external application (or 'third party') can interact with your data stored in Traffio using the API (Application Programming Interface), you must grant the third party permission. This article explains how to provide these permissions and access data through the API.
Basic Definitions & Concepts
A 'third party' is an external application or program that you will permit to access your Traffio data on your behalf. An example of a third party is StaffD, an online software package aimed at simplifying your hiring process.
An 'access token' is a long, unique password that a third party requires in order to securely access your data. Each third party has separate access tokens but only ever has one active token at a time.
The third party uses the access token to securely access your Traffio data provided by the Traffio API. You retain control of what data can be accessed by the third party.
There are two types of third party in Traffio, 'Traffio approved' and 'Personal'. Which data a third party can access and what they can do to that data is determined by the type of third party they are.
You must have 'Manager' access level role to manage third parties in Traffio.
How to Create a Third Party
Click on 'Integrations' in the main menu on the left side of the interface. This menu item will only be visible if you have a 'manager' access level role.
'Traffio-approved' third parties will be visible by default. To grant one of these approved third parties access to your data, click the arrow next to the relevant third party to generate an access token. Alternatively, you can create your own third party by clicking the 'New' button in the top-right corner of the interface.
Fill in the required details for your new third party, paying close attention to the 'Contact Email' field. The email address provided will be the one that receives access to your Traffio data when you issue a new access token (as described below).
The 'Permissions' section on the 'New third party' screen specifies the data the third party will have access to. After making your selections in this section, click 'Create' to finalize and create the third party.
At this point, the newly created third party still does not have access to your data. Refer to 'How to Create an Access Token' below to grant this access.
How to Create an Access Token
A third party needs an access token (a unique password) to interact with your data through the Traffio API.
To create an access token, go to the detail view of a third party by clicking the arrow next to their name in the 'Integrations' section. Then, click on the 'Access Tokens' tab in the top-right corner of the interface and select the 'New' button.
For 'Personal' third parties, you will see an email address field where the token will be issued. For 'Traffio-approved' third parties, this field will not appear, as it is already predetermined.
After providing a reason for issuing the token, click the 'Create' button. A pop-up window will appear explaining what happens when issuing an access token. Once you've read and understood this information, click 'Continue' to issue the token.
The token will remain in a 'pending' state until the third party activates it from the email they have received. Once the third party activates the access token, the status will change to 'Active,' granting them access to your Traffio data.
How to Revoke Access
If you need to prevent a third party from accessing your Traffio data, you can revoke any access tokens issued to them.
Go to the 'Access Tokens' tab for the third party you wish to revoke access from. Click the arrow next to the 'Active' access token, then select the 'Revoke' button on the next screen.
Once all access tokens are revoked, the third party will no longer be able to access your data through the Traffio API. The third party will not be notified of this revocation.
How to Access Data with an Access Token
Traffio's REST API can be explored directly from your browser.
To explore the data you're interested in, click on one of the menu items under the 'Available APIs' heading on the left side of the interface. The right side of the interface will display all the data methods you can interact with.
For example, to get a list of depots;
Click on the 'v1_depot' menu item.
Paste an active access token into the 'API Access Token' field at the top of the screen.
Under the heading 'GET depot' in the main area of the interface, scroll to the bottom of the form and click the blue 'Submit GET request' button.
This will present a table of information about the depots that are currently in the system.
You can filter the data returned by entering values into the forms provided for each available data method. For example, with depot data, if you know the unique identifier for a specific depot, you can enter it into the 'depot_id' field to retrieve only the information for that particular depot, excluding all others in the system.
The interactive API allows you to request data in various formats, including HTML, JSON, and CSV. To change the format of the data being requested, use the drop-down menu located to the left of the blue 'Submit GET Request' button.
What if an Access Token is Lost?
If a third party loses an access token, you should revoke it through the Traffio interface.
Access tokens that have already been generated cannot be recovered from Traffio. If you want the third party to regain access to your data, you will need to re-issue a new access token as described above.
Types of Third Party
There are two types of third parties in Traffio: 'Personal' and 'Traffio approved'. The differences between these two types are as follows:
Personal:
Multiple 'Personal' third parties can be created from the 'Integrations' area
The email address for issuing access tokens can be set from the interface
'Read' permissions can be freely configured, but 'Write' permissions are not allowed
Traffio Approved:
Managed by Traffio and cannot be created through the interface
The email address for issuing the access token cannot be viewed or modified
'Read' and 'Write' permissions are managed by Traffio and cannot be configured through the interface