OAuth 2.0 Developer Process

As a developer, you must follow the steps below to successfully implement the OAuth 2.0 protocol to access FedEx Supply Chain merchant’s data.

1. Register Application and Update OAuth Redirect URI

First, go to FedEx Supply Chain API Developer Portal to register an application. Enter the app name, description and OAuth redirect URI as shown below and click the SUBMIT button to create a new app.



Please note that the OAuth redirect URI entered in the app registration screen must match the redirect_uri field passed in the OAuth 2.0 authorize endpoint API.

NOTE: If you have already registered an application and use the custom authentication, you must update the existing app and provide the OAuth redirect URI in order to migrate to the OAuth 2.0 authentication.

2. Subscribe to the Authentication Product

In order to use the OAuth 2.0 authorize and token endpoints, you must subscribe to the authentication product in FedEx Supply Chain API Developer Portal.

3. Get OAuth 2.0 Access Token via the Access Code Flow

Before you can make any FedEx Supply Chain API call, you must get the OAuth access token using either the Access Code Flow or the Password Flow.

The Access Code Flow is the most common OAuth scheme you use to deal with OAuth servers. When you use a third-party developer’s web application to access FedEx Supply Chain Fulfillment platform, you are using the Access Code Flow to get the access token to access theFedEx Supply Chain Fulfillment Platform.

First, you need to obtain merchant’s consent by redirecting them to the FedEx Supply Chain OAuth 2.0’s authorize endpoint. After merchant logs in and grants the access, an authorization code is generated and can be used in the subsequent OAuth 2.0 token endpoint API call.

Here is an example of OAuth authorize endpoint call to open FedEx Supply Chain Fulfillment Login page:

https://api-test.supplychain.fedex.com/api/sandboc/fsc/oauth2/authorize?... &redirect_uri=https://sample-app.com/callback&scope=Fulfillment_Returns&org_name=MyOri...

This is the FedEx Supply Chain Fulfillment Login page:


You have to enter your FedEx Supply Chain Fulfilment login credentials. Upon successful authentication, you will be redirected to merchant’s consent page:


Once you click the “Allow Access”, you will be redirected to the configured redirect_uri appended with generated temporary access code (also called as Auth Code):

https://sample-app.com/callback?code=authorization_code&state=12345zyz

• code - The server returns the authorization code in the query string
• state - The server returns the same state value that you passed

Next, to get the access token, you can use the use the temporary access code from previous step to call the token endpoint.

To make the token endpoint API call, you must pass one additonaltwo required HTTP headers:
• “org_name” – to indicate your organization name. No spaces are allowed for “org_name.”

Here is an example of the Token API call, if you use CURL:

curl https://api.supplychain.fedex.com/fsc/oauth2/token \
-d “code= AAJJbW1pNPFYbC8kpOQ &client_id=7c73ssHa&client_secret=gP3iW3xQ1tAM&grant_type=authorization_code&scope=Fulfillment_Returns” \
-H “Accept: application/json“ \
-H “origin: testdomain.com” \
-H “org_name: MyOrgName”


Here is a sample response:

																																																							
{ 
	"token_type":"bearer",
	"access_token":"AAEkN2M3M2 ", 
	"expires_in":3600, 
	"scope":"Fulfillment_Returns", 
	"refresh_token":"yFGvLOKW"
}
																																																						

After you make the successful token API call, a connection with the “org_name” you specified is created in the FedEx Supply Chain system. The merchant can log in to the FedEx Supply Chain Portal to view and control the connection.

NOTE: If you are in FedEx Supply Chain API Developer Portal and click the test token endpoint, a connection will NOT be created. This allows you to test the OAuth 2.0 token endpoint but not actually create the connection.


If your access token expired, you can make a refresh token call to get a new access token:

curl https://api.supplychain.fedex.com/fsc/oauth2/token \
-d “refresh_token=AAJJbW1pNPFYbC8kpOQ&client_id=7c73ssHa&client_secret=gP3iW3xQ1tAM&grant_type=refresh_token&scope=Fulfillment_Returns” \
-X POST \
-H “Accept: application/json“ \
-H “org_name: MyOrgName”


Here is a sample Response:

																																																																							
{ 
	"token_type":"bearer",
	"access_token":"AAEkN2M3M2 ", 
	"expires_in":3600, 
	"scope":"Fulfillment_Returns", 
	"refresh_token":"yFGvLOKW"
}
																																																																							
																																																																						

4. Get OAuth 2.0 Access Token via Password Flow

We also support the OAuth 2 Password flow as the grant type so that API consumer can pass the user name and password to get an access token directly.

NOTE: You should only use this grant type only for your own application. Don’t share your FedEx Fulfillment user name and password with a third-party developer.

Here is an example of the API call if you use CURL:

curl https://api.supplychain.fedex.com/fsc/oauth2/token \
-d “client_id=7c73ssHa&client_secret=gP3iW3xQ1tAM&grant_type=password&scope=Fulfillment_Returns&username=FSC_Fulfillment_login &password=FSC_Fulfillment_Pwd" \
-X POST \
-H “Accept: application/json“ \
-H “x-org-name: MyOrgName


Here is a sample response:

																																																																																								
{
	"token_type":"bearer", 
	"access_token":"AAEkYjI0ZjYzYmQtMzNhYy00M ",
	"expires_in":3600,
	"scope":"Fulfillment_Returns", 
	"refresh_token":"AAFx8azy95HrtC7 " 
}
																																																																																								
																																																																																							

NOTE: Please make sure to use the “x-org_name” in your HTTP header for the Password Flow.

You can use the same Refresh Token call documented above to refresh the access token.

5. API Calls with Access Token

After you successfully get the OAuth access token, you can now use it to make the Fulfillment and Returns API calls. If you migrate from custom authentication to OAuth 2.0, you no longer need to pass the client_id, client_secret and custom access token in the HTTP Header. Instead, you will set the OAuth access token as a bearer token using the “Authorization” HTTP header.

Here is an example of the API call if you use CURL:

																																																																																																	curl  https://<........>/api/v1/receipts  \
				  -H “Authorization: Bearer <TOKEN>”