Logistics API Guide - Authentication

Note: This guide is meant to be accompanied with the Logistics API spec: 

https://docs.logistics-api.flexport.com/

Access Tokens

To use the Logistics API, you will need an access token. Each access token carries its own scopes. This allows you to create one access token to access products, and another one to access orders, for example.

You must be an Administrator of your organization to manage access tokens.

Once issued, access tokens do not expire unless revoked by the Administrator.

There are two ways to request an access token:

Token Management Through The Flexport Portal

API Token List

Access tokens can be created and managed in Flexport Portal. You will find in your settings a tab labeled “API Tokens”
https://portal.flexport.com/settings/api-tokens

If you are an Admin of your organization, the page will look something like this:

You are able to view and copy the token’s secret here. Please treat this secret appropriately as it is a direct password to your logistics (where scopes apply). Ensure to properly store and protect your password! We will cover disabling a token later in the guide, should you need it.

For regular users, the view is instead like this:

Do note, if a user were to click the eye icon to view the password, they will instead be greeted with a notification that it is an action for Admins only.

Generating a Token

To generate a token, click on the blue “Generate API Token” button to get started. Here you will be redirected to a Generate Token page that contains an input box for a display name of your choosing, as well as selectable checkboxes of all of the scopes available for your token.

A display name and at least one scope is required to save a new token. At the very bottom of this page will be a “Generate” button which will unlock once all requirements have been met. 

For example, let’s create a token named “Woohoo! Tutorial Token!” with the “Read Access” scope to the Products API.

You will be returned to API Tokens List page on successful generation of the token. Here you should see your newly generated token.

Edit Display Name

Now let’s say you wish to change the display name, or even deactivate the token. If you click the “Edit” button for that respective token, an Edit Token page will appear with the tools you need.

Display names can be edited and changed at will. The only requirement is that there must be a display name, as required by the generation of the token in the first place. On successful edit, you will be returned to API Tokens List page.

Important: Scopes cannot be edited or changed. Should you require a similar token with similar scopes, an entirely new token must be created in the Generate Token page.

Deactivate - Revoke Token

 

To deactivate a token is as simple as selecting the red “Deactivate token,” located at the bottom of the Edit Token page. Upon click, a final confirmation will appear.

Important: Deactivating a token is NOT reversible. Please decide wisely before deactivating your token.

On successful deactivation, you will be returned to API Tokens List page. Your token status will now read “INACTIVE.”

Generating A Token Through The Logistics API

1. To start the authentication process, make a call to the OAuth - AuthorizeRedirect endpoint. Here are some examples to help you get started:

An example of a copyable link to paste in your browser address bar:

https://logistics-api.flexport.com/logistics/api/unstable/oauth/authorize?response_type=code&client_id=identity&scope=read_logistics_products%20write_logistics_products

An example of a curl command:

curl --location 'https://logistics-api.flexport.com/logistics/api/unstable/oauth/authorize?response_type=code&client_id=identity&scope=read_logistics_products%20write_logistics_products'

• response_type must be “code”
• client_id must be “identity”
• Under scope, add in the scope(s) you would like access to. To request multiple scopes, you can join them with a space as the separator between scopes. For the respective API endpoints, the allowed scopes are:
  1. read_logistics_products write_logistics_products - access to the Products API
  2. read_logistics_reports write_logistics_reports - access to the Reports API 
  3. read_logistics_bundles write_logistics_bundles - access to the Bundles API
  4. read_logistics_orders write_logistics_orders - access to the Orders API
  5. read_logistics_webhooks write_logistics_webhooks - access to the Webhooks API
  6. read_logistics_parcels write_logistics_parcels - access to the Parcels API
  7. read_logistics_returns write_logistics_returns - access to the Returns API
  8. read_logistics_freight write_logistics_freight - access to the Freight API
  9. read_logistics_events - access to the Events API (read only)
  10. read_logistics_inbounds write_logistics_inbounds - access to the Inbounds API

2. It will redirect you to the following consent screen:
   
   
   
   
3. Login with the same credentials as your Flexport Portal account (Note: this login is case-sensitive); you will be redirected to the Flexport Portal, along with the code query parameter. It is important to note that the code will expire in about 3 minutes from the call. Here’s an example of the URL you’ve been redirected to:

https://deliverr.com/?code={received_code_value}

4. Copy that received code parameter value to make the following request to the OAuth - TokenExchange endpoint with the authorization_code grant type:

curl --location 'https://logistics-api.flexport.com/logistics/api/unstable/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=YOUR_RECEIVED_CODE_VALUE'

• Note that the request body must be in the application/x-www-form-urlencoded format

5. You will receive a response like this:

{
    "access_token": {valid access token}
}

6. The access token does not expire. Pass in the access_token value as a Bearer token in the Authorization header to authenticate your requests to the Logistics API. Here are some curl examples to help you get started. Remember to specify an API version inside of {version}.

GetProduct (provided a Product DSKU - Ex: DYOURDSKU01):

curl --location 'https://logistics-api.flexport.com/logistics/api/{version}/products/DYOURDSKU01 \
--header 'Authorization: Bearer YOUR_VALID_ACCESS_TOKEN'

GetOrder (provided an Order Id - Ex: YOURORDERID):

curl --location 'https://logistics-api.flexport.com/logistics/api/{version}/orders/YOURORDERID \
--header 'Authorization: Bearer YOUR_VALID_ACCESS_TOKEN'

Partner Access

If you wish to develop an application that could be used by more than one merchant, take a look at the guide for Partner Access (TBD).