Authentication

9 min

You must replace the api-key with your personal API keys

The FourKites® API uses API keys to authenticate requests. Note that the users will now have the ability to view and manage the API Keys in the FourKites® platform.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via API Key Auth. Provide your API key as the apikey header.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

curl 'api_endpoint_here' \
  -H 'apikey: your_api_key' \
  -H 'Accept: application/vnd.fourkites.v1+json' \
  -H 'Content-Type: application/json'

Refer to the FourKites® Developer Portal KnowledgeBase article to learn more about Authentication. Note that the users must reach out to their Company Admins for API Keys.

Authentication Mechanisms

Different APIs follow different authentication mechanisms. Here are a few pointers to note:

APIs with the endpoint URL https://api.fourkites.com will require API key authentication

APIs with the endpoint URL https://tracking-api.fourkites.com will require basic authentication. Here are some examples: Insights API, Get Relationships, Mark Shipment Hot, Mark Shipment Delivered

Some APIs would require client_id, which you can get from the FourKites Implementation Manager.

We also have an alternative to API Key Authentication and that is OAuth2 Flow. Read more about it below.

OAuth2 Flow

As an alternative to API Key Authentication, we also provide users the option to choose OAuth2 Flow. We support the client credentials flow of OAuth2. Following successful authentication, the calling application will have access to an Access Token, which can be used to call the APIs.

Reach out to your Customer Success Manager at FourKites to get OAuth2 enabled. Once OAuth2 is enabled, you cannot use the standard API Key authentication flow.

Once the OAuth2 framework is enabled, use the following steps to call the API:

Creating the Access Token: From the authorized application, request an Access Token for your API.

Making API Calls: Use the retrieved Access Token to call your API.

Basic Authentication

FourKites API supports standard HTTP Basic Authentication. For this authentication method, the customer will receive a username & password when they register with FourKites as an API user. The credentials (username & password) should be passed in the Authorization header for every request.

Attaching Credentials

When the client wants to make a request to FourKItes API it may use the Authorization header to send the authentication credentials to the server.

The username and password are combined into a string separated by a colon, e.g.: username: password

The resulting string is encoded using Base64 algorithm. Trim the encoded string off any new line or carriage return character.

The authentication method ("Basic") followed by a space is inserted before the encoded string from step 2 and is passed in Authorization header of every request.

Illustration

Say the API credentials are as follows:

Username: username

Password: password

Combine username and password by adding a colon (:) in between username and password. This would result in the string "username:password".

Encode the resulting string using Base64 algorithm. Base64 encoded string for "username:password" is "dXNlcm5hbWU6cGFzc3dvcmQ=\n". Remove the new line character (\n) at the end of the encoded string to yield "dXNlcm5hbWU6cGFzc3dvcmQ="

Insert "Basic " in front of the encoded string to yield "Basic dXNlcm5hbWU6cGFzc3dvcmQ=". Pass the resulting string (Basic dXNlcm5hbWU6cGFzc3dvcmQ=) in Authorization header of every request.

Creating the Access Token

To access your API, you must request/create an Access Token for it. To do so, you will need to POST to the token URL.

Parameters

curl --location --request POST 'https://api.fourkites.com/shipments/oauth2/token' \
--header 'apikey: your_api_key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "client_id": "your_api_key",
    "client_secret": "your_client_secret",
    "grant_type": "client_credentials"
}'

Parameter	Type	Default	Description
grant_type			Set this to "client_credentials".
client_id			Your application's API Key.
client_secret			Your application's Client Secret.

Response

If all goes well, you'll receive an HTTP 200 response with a payload containing access_token, token_type, and expires_in values:

{
    "token_type": "bearer",
    "access_token": "4dUG8PyaojBHuN3odr4MrWEhlJlYZmUo",
    "expires_in": 7200
}

Making API Calls

To call your API, the application must pass the retrieved Access Token as a Bearer token in the Authorization header of your HTTP request.

The token can be refreshed before it expires in seconds to make successful API calls over a longer time period.

curl --location --request GET 'https://api.fourkites.com/shipments' \
--header 'apikey: your_api_key' \
--header 'Authorization: Bearer 4dUG8PyaojBHuN3odr4MrWEhlJlYZmUo'