API Authentication - Global-e Docs

Global-e offers two types of security methods for communication from the Merchant / Platform to Global-e using API calls. The selected key is passed in the API header.

JSON Web Token (JWT) Authentication - Unique key generated to the Merchant, based on username and password provided by Global-e (preferred method).
Merchant GUID - Unique key provided to the Merchant, by Global-e.

Use the API UserName header and the Authorization header, including the token retrieved via the GetAuthenticationToken API using merchant-specific credentials (provided by Global‑e).

JWT Authentication

The JSON Web Token (JWT) authentication method is used by merchants authenticating their APIs sent to Global-e APIs. It is possible to configure JWT authentication for a specific API, while other APIs will use merchant GUID authentication.

To Create the JWT Token

Prerequisites The following setup should be done before applying to a JWT token:

Global-e adds a user for the merchant in Global-e DB. The name of the user is identified by Global-e.
Global-e confirms with the merchant the name created.
The Merchant generates a key using Postman / Swagger (not in the Production environment) using the Authentication Service - CreateUpdateUser API.
The Merchant implements the GetToken API to renew the token. If expired - Global-e API returns an error.

Note: Make sure to use the Global-e API environment such as connect.bglobale.com, or api.global-e.com. Create the Token The following steps should be implemented by the merchant / Platform for every API call to GE CORE:

Send user name + password to “/Authentication/GetAuthenticationToken” API. The username and password are provided to the merchant by GE.
Receive JWT token. The JWT token can be cached and reused by the merchant until it expires (15 minutes is the default TTL).
Add the returned JWT token to the HTTP header in every API call.

Note: The returned token and the username are sent as part of the API request, in the HTTP request header.

GetAuthenticationToken API

Use the GetAuthenticationToken API to obtain a JSON web token (JWT). Send a username and password that are obtained by Global-e and receive a JWT token. The returned token and the username are sent as part of the API request, in the HTTP request header. Method/URL

POST https://{globale_sever}/Authentication/GetAuthenticationToken

Call the GetAuthenticationToken API as in the following URL: https://{server_name}/Authentication/GetAuthenticationToken

Parameter	Type	Description
`Reason`	String	Text that optionally describes the reason for Success status
`Success`	Boolean	Indicates if the API call was successful. Success property value may be only TRUE. Otherwise, an ErrorInfo is returned.
`Token`	String	JWT encoded token.
`TTLInMinutes`	Int	The Token expiry time in minutes.

Examples Request

{
    "userName": "yuvalta",
    "password": "password"
}

Success Response

{
    “Success”: true,
    “Token”:     
    "<JWT_TOKEN>",    
    “TTLInMinutes”: 15    
}

Fail Response

{
   "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "|f1c6be73-42d43d27971c276a.",
    "errors": {
           "Password": [
            "Password length can't be less than 8 or greater than 50 characters."
           ]
     }
}

By default, the token expires within 15 minutes unless you specify that the token should be valid for longer.

Using the JWT Key in the Header

Once the token has been generated, call the API of choice using the relevant credentials in the header. Example key= ”Authorization” | value = "my_jwt_token" Key= ”UserName”| value = "userName" Example of JWT in Header

curl -X POST https://[globale domain]/[API] \
     -H "Authorization: Bearer my_jwt_token" \
     -H "UserName: userName" \
     -H "Content-Type: application/json"

Interaction Diagram

The diagram below shows the interaction between the Merchant code, the Global‑e API code, and the authentication service.

MerchantGUID Authentication

To implement API calls with Global-e the merchantGUID provided by Global-e must be included in the call, to ensure successful authentication. For the authentication, make sure to include your Merchant GUID as part of each call body parameters or as part of the header, so that Global-e can verify your identity. Make sure to use the appropriate merchantGUID, depending on the Global‑e integration environment used for development or production purposes. See Global-e Environments. For each endpoint, perform the following steps:

Add the MerchantGUID in the request header as illustrated below. Make sure to use the appropriate merchantGUID, depending on the Global‑e integration environment used, development or production.
Make sure to implement the API on the server side (rather than calling it from the client side). Alternatively, implement it outside of the frontend layer to avoid exposing the merchant GUID publicly.

MerchantGUID Implementation The MerchantGUID indicated in the API should be specified in the API Header. Note: Never add the merchantGUID as a path parameter in the URL. MerchantGUID as part of the header Add your MerchantGUID as part of the header as in the following example:

curl --location 'https://[globale domain]/[API]' \
--header 'MerchantGUID: <MERCHANT_GUID>' \
--header 'Content-Type: application/json' \
--data-raw '{"key1":"value1", "key2":"value2"}'

Example

curl -X GET https://[globale domain]/[API] \
-H "Authorization: Bearer jwt_token_here" \
-H "Content-Type: application/json" \
-d '{
	"ProviderCode": "Loop",
	"OrderId": "GE314856569TS",
        "Email": "globale@gmail.com",
	"MerchantRMANumber": "RM132",
	"ShippingCost": 10.0,
	"CurrencyCode": "USD",
	"ReturnShippingTypeId": 2,
	"ReturnShippingMethodId": null,
	"ReturnedProducts": [
		{
			"ProductCode": "DKB500680.M8",
			"ProductSecondaryCode": "",
			"CartItemId": null,
			"ReturnQuantity": 1,
			"MerchantReturnReasonCode": "",
			"MerchantReturnReasonDescription": "Return Reason from GRD request for product 1"
		},
		{
			"ProductCode": "B7ECS.C8",
			"ProductSecondaryCode": "",
			"CartItemId": 1,
			"ReturnQuantity": 1,
			"MerchantReturnReasonCode": "TTT",
			"MerchantReturnReasonDescription": "Return Reason from GRD request for product 2"
		}
	]
}'

Rotating Your Merchant GUID

Your Merchant GUID is the credential that identifies your store to Global-e, so it should be treated as a secret and replaced periodically, just as you would rotate any other API credential. Follow the instructions for your platform below to rotate your Merchant GUID:

IP Whitelisting

As part of strengthening the security of the integration between your systems and Global-e, we recommend whitelisting the IP addresses that access our APIs, so that only traffic from your approved infrastructure can access your Global-e account. As part of your integration, please provide the full list of public IP addresses (or CIDR ranges) that you use to connect to Global-e. The required list may include every system and application with an interface to Global-e:

Production servers and any backend calling Global-e APIs
OMS, ERP or middleware that syncs orders, catalog, product feeds or returns
Warehouse, 3PL or WMS systems that handle shipping activities
Integration partners or agencies acting on your behalf
Staging or test environments, marked as such

When your IP addresses change in the future, please notify us before the change.

Any system that is not whitelisted may be prevented from accessing Global-e systems and performing expected operations.