Permissions and Credentials

Global-e offers two types of security methods for communication from the Merchant / Platform to Global-e using API calls.

1. Merchant GUID - Unique key provided to the Merchant, by Global-e

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

The API UserName header and the Authorization header, including the token retrieved via the GetAuthenticationToken API using merchant-specific credentials (provided to you by Global‑e). See the Authentication section under ???.

Authentication: MerchantGUID

To implement API calls with Global-e the only required information is the merchantGUID provided by Global-e.

For authentication, make sure to include your Merchant GUID as part of each call 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 in URL

Add your MerchantGUID as part of each API URL.

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 illustrated below.

curl --location 'https://[globale domain]/[API]' \
--header 'MerchantGUID: D2ED2A7F-F6ED-4CCB-B611-B44AC8D02250' \
--header 'Content-Type: application/json' \
--data-raw '

JWT Authentication

The JSON Web Token (JWT) authentication method is used for merchants authenticating the Global-e APIs.

It is possible to configure JWT authentication for a specific API, while other APIs will use merchant GUID authentication.

Consider using JWT for the following API calls:

SendOrderToMerchant (Platform)

UpdateOrderStatus (Platform)

PerformOrderPayment (Platform)

ValidateVoucher

Gift cards APIs: ValidateGiftCard, RedeemGiftCard, RefundGiftCard

SendRMAInfoToMerchant

NotifyOrderRefund

UpdateParcelDispatch

Less common : UpdateOrderShippingInfo

Obtaining JWT

Prerequisites

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

Global-e (Integration Engineer) adds a user for the merchant in Global-e DB. The name of the user is identified by Global-e, to avoid a debate loop with the merchant.
Global-e Integration Engineer 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

Provide the two credentials parameters:

key=”Authorization”, value= <token>

Key=”UserName”, value=<username>

Call the GetAuthenticationToken API as in the following URL:

Example: https://connect.bglobale.com/Authentication/GetAuthenticationToken

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.

Structure of the Get Token Response

bool Success

Indicates if the API method call was successful. Success property value may be only TRUE. Otherwise, ErrorInfo is returned instead (like in any API method, as described above in this document).

string Reason (optional)

Text that optionally describes the reason for Success status.

string Token

JWT encoded token.

int TTLInMinutes

The Token expires in minutes.

Using the JWT Key

Once the token has been generated, call the API of choice (CreateOrderRefund, OUDV2) using the following credentials in the header.

Example

key= ”Authorization” | value = token Key= ”UserName”| value = userName