Skip to main content
The CoCart API provides multiple authentication methods to suit different needs. While the Products API and Cart API are publicly accessible without authentication, authenticating users enables personalized shopping experiences.

​
Public vs. Authenticated Access

  • Public Access: Products API and Cart API
  • Authenticated Access: Required for registered customers to access their personal carts or special access/prices to products

​
Customer Authentication Methods

The use of Basic Authentication is only required should your store allow customer registration or provide membership access for specially discounted prices that can only be made available if the user has identified themselves. To make a successful request to an API that requires Basic Authentication, you must pass one of the identify methods we support combined as an authorization header for each request.
When building a request using Basic Authentication, make sure you add the Authentication: Basic HTTP header with encoded credentials over HTTPS. Requests made over plain HTTP will fail. Authentication establishes a secure customer session.
In the following request examples, you would replace <username>, <email_address>, <phone_number> and <password> with your credentials before sending the request:
  • Username + Password
  • Email + Password
  • Phone Number + Password
curl -X GET 'https://your-store.com/wp-json/cocart/v2/cart' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic base64_encode(<username>:<password>)'

​
Storing Authentication Credentials

After successful authentication, securely store the credentials using one of these methods:
  • Browser Storage
    • LocalStorage (with encryption)
    • SessionStorage (for temporary sessions)
  • Storage Libraries
  • Native Storage
    • SQLite - For mobile applications
    • Hive - For Flutter applications
    • Secure Keychain/Keystore for mobile platforms
Learn more about web storage For enhanced security, we strongly recommend using JWT authentication when available. JWT provides:
  • Stateless authentication
  • Better security
  • Reduced server load
  • Easier mobile/desktop integration
If JWT authentication is enabled, use the token received after login for subsequent requests: 
curl -X GET 'https://your-store.com/wp-json/cocart/v2/cart' \
  -H 'Authorization: Bearer jwt_token'

​
Cart Session Management

​
Authenticating with Existing Cart

If a customer begins shopping while unauthenticated, you can transfer their cart items during authentication. See Authenticating a customer with an existing cart for the process.
Maintain consistent authentication across all routes after customer login to preserve the cart session. Failing to do so will create new sessions and lose cart data.

​
Administrator Authentication

The Sessions API requires WooCommerce REST API Key authentication.
  1. Navigate to WooCommerce → Settings → Advanced → REST API
  2. Generate new keys with READ/WRITE permissions
  3. Use the keys for Sessions API authentication:
curl -X GET 'https://your-store.com/wp-json/cocart/v2/sessions' \
  -H 'Authorization: Basic base64_encode(ck_XXXX:cs_XXXX)'

​
About Base64 Encoding

  • base64_encode() is a PHP function
  • btoa() is a JavaScript function
  • Both perform Base64 encoding, but are used in different environments
  • For Node.js, use Buffer.from(str).toString('base64')
  • For React Native, use import { encode } from 'base-64'
$auth = base64_encode("username:password");

​
Trouble with Authentication?

If your server configuration doesn’t properly handle the Authorization header, you can pass credentials as query parameters: 
/wp-json/cocart/v2/cart?username=customer&password=secret
However, these methods are less secure and should be used only as a fallback.

​
Web storage & cookies

There are two types of web storage: LocalStorage and SessionStorage. These were created as improvements to using Cookies since the storage capacity for web storage is much higher than Cookie storage. However, there are different pros and cons to each of these storage options. LocalStorage Anything stored in local web storage is persistent. This means that the data will persist until the data is explicitly deleted. Depending on the needs of your project, you might view this as a positive. However, you should be mindful of using LocalStorage, since any changes/additions to data will be available on all future visits to the webpage in question. We would not usually recommend using LocalStorage, although there may be a few exceptions to this. If you decide to use LocalStorage, it is good to know that it supports the same-origin policy, so all data stored here will only be available via the same origin. An added performance perk of using LocalStorage would be a resulting decrease in client-server traffic since the data does not have to be sent back to the server for every HTTP request. SessionStorage SessionStorage is similar to LocalStorage, but the key difference is that SessionStorage is not persistent. Once the window (or tab, depending on which browser you are using) that was used to write to SessionStorage is closed, the data will be lost. This is useful in restricting read access to your token within a user session. Using SessionStorage is normally more preferable than LocalStorage when thinking in terms of security. Like LocalStorage, the perks of same-origin policy support and decreased client-server traffic apply to SessionStorage as well. Cookies Cookies are the more traditional way to store session data. You can set an expiration time for each cookie, which would allow for ease of revocability and restriction of access. However, the client-server traffic would definitely increase when using cookies, since the data is being sent back to the server for every HTTP request. If you decide to use cookies, you need to protect against session hijacking. By default, cookies are sent in plaintext over HTTP, which makes their contents vulnerable to packet sniffing and/or man-in-the-middle attacks where attackers may modify your traffic. You should always enforce HTTPS to protect your data in transit. This will provide confidentiality, integrity (of the data), and authentication. However, if your web application or site is available both through HTTP and HTTPS, you will also want to use the ‘Secure’ flag on the cookie. This will prevent attackers from being able to send links to the HTTP version of your site to a user and listening in on the resulting HTTP request generated. Another secondary defense against session hijacking when using cookies would be to validate the user’s identity again before any high-impact actions are carried out. One other flag to consider for improving the security of your cookies would be the ‘HttpOnly’ flag. This flag tells the browser that the cookie in question shall only be accessible from the server specified. Any attempts made by client-side scripts would be forbidden by this flag, therefore helping to protect against most cross-site scripting (XSS) attacks.
WooCommerce uses the cookie method natively for handling the cart session but CoCart does not. The session cookie prevented CoCart supporting guest customers and slowed down the performance of the API.
Troubleshoot Authentication Issues →
⌘I