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 theX-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.