How to use

This API plugin incorporates a dual-layer authentication mechanism to ensure secure access and operation:

Layer 1: JWT Access Token

The first layer of security is a JWT access token, generated based on a Secret Key set within the plugin's configuration page. This token is essential for authorizing most API requests, providing a secure method to validate user sessions.

Layer 2: Application API Key

The second security layer is the Application API Key, which authorizes all requests related to a specific store by matching them with the request URL. It's vital to store this key securely on the client side as it must be included in the header of each API request. This can be found on the plugin's application menu page.

Implementation Steps for Developers:

Step 1: Create an Application

Navigate to the applications page to add a new application, if you haven't already. Upon creation, the Application API Key will be visible in the applications grid.

• It's crucial to save this key as it's required for future requests.
• For certain methods, only the application API key is needed to make HTTP requests:
  • /api/PublicGeneral/Ping
  • /api/PublicGeneral/GetLocaleStringResources
  • /api/PublicGeneral/GetSettings
  • /api/PublicCustomer/GetGuestToken

Step 2: Obtaining a JWT access token

• To obtain a JWT access token, initiate a request to /api/PublicCustomer/GetGuestToken with the application API key in the X-API-KEY header.
• Successfully doing so will provide an AccessToken in the response, which should be saved for authorizing further actions and accessing other public methods.
• The response also includes a RefreshToken and its expiration, which are necessary for renewing the access token upon expiration.

Sample Request for Guest Token (C# Code)

var client = new RestClient("https://yourstore.com/api/PublicCustomer/GetGuestToken");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("X-API-KEY", "<API Key>");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

Sample Response (JSON)

{
  "CustomerId": -52828876,
  "AccessToken": "occaecat est qui",
  "RefreshToken": "Ut",
  "RefreshTokenExpiration": "1957-07-09T07:32:43.022Z"
}

Step 3: Authentication

Authentication is needed here to authenticate or login a guest or registered customer as per the nopCommerce application flow. To authenticate a nopCommerce customer (both guest or registered), send a request to /api/PublicCustomer/Login with the application API key and guest access token in the respective headers. The request body should include the UsernameOrEmail and Password in case if you want to login with a registered customer.

Sample Request for Login

var client = new RestClient("https://yourstore.com/api/PublicCustomer/Login");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("X-API-KEY", "<API Key>");
request.AddHeader("Authorization", "Bearer <Access Token>");
var body = @"{" + "\n" +
@"    ""Password"": ""mollit proident in veniam minim""," + "\n" +
@"    ""UsernameOrEmail"": ""velit nulla cupidatat elit""" + "\n" +
@"}";
request.AddParameter("text/plain", body,  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

Sample Response

{
  "IsImpersonationAllowed": true,
  "CustomerId": -65178875,
  "AccessToken": "laborum",
  "RefreshToken": "ut",
  "RefreshTokenExpiration": "2018-11-13T03:06:10.020Z"
}

These steps outline a structured approach for developers to effectively implement and utilize the public API, ensuring secure and authenticated access throughout the process.

Note: It is important to use the AccessToken obtained in the previous HTTP response while making a new HTTP request and follow the same pattern throughout your application.