Overview
Just as Traffio integrates with a number of external applications for invoicing, payroll and other purposes, 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 inside Traffio using the API (Application Programming Interface), you must give the third party permission to do so. This article explains how to provide these permissions and access data from the API.
Basic Definitions & Concepts
A 'third party' is an external application or program that you will permitt 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 of the interface. You will only see this menu item if you have an access level role of 'manager'.
'Traffio approved' third parties will be visible by default. If you want one of these approved third parties to access your data, click the arrow next to the appropriate one to generate an access token. Otherwise, create your own third party by clicking the 'New' button in the top-right area of the interface.
Complete the details required for your new third party, paying particular attention to the 'Contact Email' field. The email address provided here will ultimately receive access to your Traffio data when you issue a new access token (see below).
The 'Permissions' area of the 'New third party' screen determines what data the third party will have access to. Once you have make your selections in this area, click 'Create' and you have now created a third party.
At this point, the newly created third party does not have access to your data yet. See 'How to Create an Access Token' below to provide this access.
How to Create an Access Token
A third party requires an access token (a unique password) to interact with your data via the Traffio API.
To create an access token, navigate to the detail view of a third party by clicking on the arrow next to their name from the 'Integrations' area. Click on the 'Access Tokens' tab in the top-right of the interface and then the 'New' button.
For 'Personal' third parties, you will see an email address field to which the token will be issued. For 'Traffio approved' third parties, you will not see this field as it is predetermined.
Once you have also provided a reason for issuing a token, you can click the 'Create' button. A popup window will appear describing what happens when issuing an access token. Once you have read and understood this information, click 'Continue' to issue the token.
The token will be in a 'pending' state until the third party has activated it from the email they have now received. When the third party has activated the access token, this state will change to 'Active' and they now have access to your Traffio data.
How to Revoke Access
If you need to stop a third party from accessing your Traffio data, you can revoke any access tokens that have been issued to them.
Navigate to the 'Access Tokens' tab on the third party you wish to revoke access from. Click the arrow on the 'Active' access token and then the 'Revoke' button on the next screen.
With all access tokens in a revoked state, the third party will no longer be able to access your data using the Traffio API. The third party will not be informed of this revocation.
How to Access Data with an Access Token
Traffio's REST API can be explored from your browser. Click here to access the interactive API.
Navigate to the data you are interested in by clicking on one of the menu items under the 'Available APIs' heading located to the left of the interface. The right-hand side of the interface will now show all of 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 to be returned by entering values into the forms shown for each available data method. In the case of the depot data, for example, if you know the unique identifier for a depot you can enter it into the 'depot_id' form field to retrieve just the information about that particular depot and exclude all other depots in the system.
The interactive API also permits you to request the data in a variety of formats including; HTML, JSON and CSV. Use the drop-down field located to the left of the blue 'Submit GET reques' button to change the format of the data being requested.
What if an Access Token is Lost
If a third party loses an access token you should revoke it from the Traffio interface.
Access tokens that have already been generated cannot be recovered from Traffio. If you want the third party to have access to your data again, you must re-issue a new access token to as described above.
Types of Third Party
There are two types of third parties in Traffio; 'Personal' and 'Traffio approved'. The difference between these two types are;
'Personal':
Multiple 'Personal' third parties can be created from the 'Integrations' area.
The email address to issue the access tokens can be set from the interface.
'Read' permissions can be freely set. 'Write' permissions are not permitted.
'Traffio approved':
Managed by Traffio and cannot be created by the interface.
The email address to issue the access token cannot be seen or changed.
'Read' and 'Write' permissions are managed by Traffio and cannot be set from the interface.