Set Up and Authentication

Enable API Requests

To set up your SoftSlate Commerce store for API access, you must first enable API requests through the global setting on the Store Settings -> Advanced Settings screen. The setting is name "Enable API Requests?" and it must be set to yes for API request to work. Here's a screenshot of where the setting is located:

By default this setting is set to no, so you have to turn it on when you're ready to use the API.

Public Operations

Once the above setting is switched on, the "Public Operations" of the API are available to use. The reference documentation for Public Operations on the demo site is located here:

https://www.softslate.com/demo/administrator/apiReference/index.html#/Public_Operations

Public Operations include requests that any user can make to the system, such as viewing product catalog information, searching for products, and adding and editing items in a cart. They correspond to the public interface for the store.

CSRF Tokens for Public Operations

Most requests made to a Public Operations API endpoint require a Cross-Site Request Forgery token to ensure that the request is originating from the site itself. When testing the API, you can use the "CSRF Token" request to retrieve the token for your session:

The value of this token must then be used as a parameter to many of the Public Operations requests.

Administrative Operations

API requests that are not under Public Operations require additional authentication because these requests have access to view and modify store data that might be sensitive. These requests correspond to the Administrator interface under /administrator. Follow these steps to enable access to these operations.

Create an Administrator as an API User

An API User is just like any other user in the Administrator, but the "Is API User?" flag is set to true:

Setting the "Is API User?" flag to yes allows that particular user to log in using the parameters apiLoginID (for the user name) and apiAuthenticationToken (for the password), and make administrative API requests. These two parameters can be specified as regular request parameters, or, for better security, as HTTP headers of the same name (apiLoginID and apiAuthenticationToken).

If the API user is not set up correctly or there's a problem with the user name or password, you'll see the following "Login failed." response:

{
  "success": false,
  "errors": [
    "Login failed."
  ],
  "messages": [],
  "jsonResult": {}
}

Add Roles for the API User

When an API user, or any Administrator for that matter, is first created, the user will be able to login but won't be allowed to perform any functions. You must next give the user roles to perform:

If the API user attempts to execute a function it is not allowed to, you'll see the following 'permission denied' response:

{
  "success": false,
  "errors": [
    "We\u0027re sorry, you do not have permission for the requested action. Please contact a superuser to assign the necessary roles to grant access."
  ],
  "messages": [],
  "jsonResult": {}
}

Security Considerations for API Users

Since API Users will be able to login and execute actions immediately within the same request, arguably special security considerations should be made. Among the things to consider:

• API Users will likely be used by programming code, not human beings. For this reason, why not make the password longer and more difficult than you would normally? A human being is not going to have to enter the password at any point. You will just be copying it and pasting it into a program. This will reduce the possibility of a brute-force compromise.
• Consider setting the "Reject Non-Secure Administrator Requests," to force API requests and other admin requests to use HTTPS. The setting may be found on the Security Settings -> Session Management Settings screen.
• The roles given to API users should ideally be restricted to prevent abuse or mistakes. Avoid giving the API user superuser or administrator roles unless there's a good reason.
• If possible, pass the apiLoginID and apiAuthenticationToken as HTTP headers rather then regular request parameters. This will reduce the possibility the values will be logged or exposed via the URL.
• Similarly, use the POST method to send API requests so that sensitive information is not exposed as part of the request URL. URLs are easy to copy, and they may be logged on the server or elsewhere.