NAV

Access tokens

All Ecwid REST API requests require authentication. Ecwid supports oAuth2 protocol to provide applications with an easy way to authenticate and access store data on behalf of the user with access tokens.

There are two types of access tokens in Ecwid: private and public tokens. Private ones can’t be shared publicly as they provide access to modify store data through the REST API. Public tokens on the other hand have read-only access, so they can be used anywhere to get store details through the REST API in your apps.

Ecwid user grants or denies access to certain data in their store for the particular application - then the application gets its own secure access token (and optional public token) upon authorization and uses that token as a key to make REST API calls to Ecwid.

Private access token

Private access token example

{
    "access_token": "secure_adasjkhndjksnmkasjhdASDHasjdnhasa"
}

Private access token provides access to Ecwid API to retrieve and change store data on behalf of the user who installed your application in their store. It doesn’t expire, so it is available to you at all times. You will only need to get a new access token in case a user uninstalls the application from their store and installs your application back again.

With private access token you can use any method within the access scope range that you requested from an Ecwid user on initial steps of oAuth process.

After the moment user installs your app, it can store that token securely in your database for that user. So it’s not necessary to go through the standard oAuth flow each time you need to make a request to Ecwid API.

Public access token

Public access token example

{
    "public_token": "public_asdkjlsaASKDjaslkdASmndcasmrdgaSj"
}

Public token provides limited access to public store data via REST API interface. While private tokens allow you to modify something in a store, like update an order status or change storkc levels, public tokens can only get limited information from a store and create orders with limitations.

You are able to retrieve public token in any part of your application:

With public access token you can use several REST API endpoints from anywhere (client-side JavaScript, widget integration codes, etc.). These methods are available for public token regardless of the other access scope your requested from a store – you only need the public_storefront scope to use them:

Access scopes

Scopes are permissions that identifies the scope of access your application requests from the user. Below you can see the names of access scopes that exist in Ecwid API and their description.

Each application has their specified set of access scopes which are required for this applicaiton. If you specify additional scopes, that excess the specified ones for the app in Ecwid, you will see an error message. So if you need to add more access scopes - please contact us to update your app.

Access scopeNotes
read_store_profileGet store name and general settings, get store admin email, get updates statistics etc. Requested in all cases even if not specified
update_store_profileSet taxes, update invoice logo, change Starter Site domain, close store for maintenance etc.
read_catalogSearch products, get product options/variations etc. Also allows to receive push updates (webhooks) about changes in store products.
update_catalogUpdate product prices, upload images and e-goods, modify product attributes, delete products and categories, etc.
create_catalogCreate new products
read_ordersGet sales for a given period, retrieve order details etc. Also allows to receive push updates (webhooks) about changes in store orders.
update_ordersChange order totals, switch order status, cancel orders, delete orders, etc. Requires read_orders scope to function
create_ordersPlace a new order in the store
read_customersSearch customers or retrieve some particular customer data
update_customersChange customer profile data, add items to the customer address book, delete customers, etc.
create_customersAdd a new customer to the store’s Customers list
read_discount_couponsGet the list of discount coupons or retrieve some particular coupon details
update_discount_couponsChange the coupon expiration date or limit its number of use, update coupon code, delete coupon codes, etc.
create_discount_couponsAdd a new discount coupon
customize_storefrontAttach a custom JS/CSS to the storefront on the fly to modify its look and feel (see Customizing storefront)
add_to_cpAdd a new tab to merchant control panel (see Embedding apps)
add_shipping_methodAdd a new shipping method to the store (see Custom Shipping API)
add_payment_methodAdd a new payment method to the store (see Add Payment Method)
public_storefrontGet public store details with public access token
customize_cart_calculationApply custom discounts to orders in real time