---
title: Authentication
slug: fourkites-api-reference/ficf-authentication
description: Learn how to authenticate your API requests with FourKites® using API keys or OAuth2 flow. Ensure secure communication with HTTPS and avoid failed requests by including proper authentication. Discover how to create an access token for OAuth2 authenticatio
createdAt: 2023-04-14T06:58:52.000Z
---

:::hint{type="info"}
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](http://en.wikipedia.org/wiki/HTTP_Secure)**. Calls made over plain HTTP will fail. API requests without authentication will also fail**.

```curl
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](https://support-fourkites.force.com/hc/s/article/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](https://docs.fourkites.com/api-reference/insights-api), [Get Relationships](https://docs.fourkites.com/api-reference/get-relationships), [Mark Shipment Hot](https://docs.fourkites.com/api-reference/mark-shipment-hot), [Mark Shipment Delivered](https://docs.fourkites.com/api-reference/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.

:::hint{type="info"}
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.

1. The username and password are combined into a string separated by a colon, e.g.: *username*:* password*
2. The resulting string is encoded using Base64 algorithm. Trim the encoded string off any new line or carriage return character.
3. 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
 

1. Combine username and password by adding a colon (:) in between username and password. This would result in the string "username\:password".
2. 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="
3. 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
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:

```curl
{
    "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
curl --location --request GET 'https://api.fourkites.com/shipments' \
--header 'apikey: your_api_key' \
--header 'Authorization: Bearer 4dUG8PyaojBHuN3odr4MrWEhlJlYZmUo'
```