> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.bglobale.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:
1. Global-e adds a user for the merchant in Global-e DB. The name of the user is identified by Global-e.
2. Global-e confirms with the merchant the name created.
3. The Merchant generates a key using Postman / Swagger (not in the Production environment) using the Authentication Service - *CreateUpdateUser* API.
4. 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:
1. Send user name + password to “/Authentication/GetAuthenticationToken” API. The username and password are provided to the merchant by GE.
2. Receive JWT token. The JWT token can be cached and reused by the merchant until it expires (15 minutes is the default TTL).
3. 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
###### 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. With that, the MerchantGUID must still be specified in the request URL, in addition to the JWT token in the HTTP header
**Method/URL**
```
POST https://{globale_sever}/Authentication/GetAuthenticationToken
```
Call the `GetAuthenticationToken` API as in the following URL:
[https://\{server\_name}/Authentication/GetAuthenticationToken](https://connect.bglobale.com/Authentication/GetAuthenticationToken)
| Parameter | Type | Description | Mandatory |
| -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- | --------- |
| `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."
]
}
}
```
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](/shipping-with-non-global-e-carriers#global-e-environments-722540).
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"}'
```
**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"
}
]
}'
```