API Authentication

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 merchant GUID must still be specified in the request URL, in addition to the JWT token in the HTTP header.

Note: The returned token and the username are sent as part of the API request, in the HTTP request header. With that, the MerchantGUID must still be specified in the request URL, in addition to the JWT token in the HTTP header

URL

Call the GetAuthenticationToken API as in the following URL:

https://{server_name}/Authentication/GetAuthenticationToken

Parameters

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”:     
    "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.InsgXHUwMDI3RVhwaXJlc1x1MDAyNyA6IFx1MDAyNzU0NTQ1N 
    DU0NTQ1NDU0XHUwMDI3LCBcdTAwMjdNZXJjaGFudEdVSURcdTAwMjcgOiBcdTAwMjdqZ2RzZ2pkc2pnZ 
    GhzZ2RzaGdkaHNnZGhnXHUwMDI3IH0i.ZLUuZIMraFXVRcpZzkOQWdFDmRI4ypLXK6bNnVxG4do”    
    “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."
           ]
     }
}{ "destinationCountry":"USA",   "amount":"50", "currencyCode":"USD",  "productCodes":[]
}

Note

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: D2ED2A7F-F6ED-4CCB-B611-B44AC8D02250' \
--header 'Content-Type: application/json' \
--data-raw '{"key1":"value1", "key2":"value2"}'