Apps outside the Ecwid App Market

Overview

Some applications are supposed to be installed/connected to a user store outside the Ecwid App Market. For example, desktop applications, iOS/Android apps, self-hosted CMS plugins etc. Such application can be listed in the Ecwid App Market as well, but it's assumed that a user (merchant) initiates the app installation on their desktop, mobile device or a sitebuilder dashboard. So, you as a developer of such application should handle the full oAuth flow. Read below for more details.

Getting an access token

Retrieving an access token in a complete oAuth flow includes the following steps:

1. Your app sends the user to the Ecwid authorization dialog.
2. Upon authorization, Ecwid redirects the user to the app return URL (reach out to us at [email protected] to set or change it) specified in the request.
3. Your app requests an access token from Ecwid.

📘

User needs to go through all these steps only once in order for your app to get and store access token for that user. This token will be used in any call you make to Ecwid API on behalf of the user.

1. Send user to the Ecwid authorization/consent dialog

Your application sends the user to Ecwid authorization dialog available on the Ecwid oAuth endpoint.

GET https://my.ecwid.com/api/oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&scope={scope}

📘

All parameters are mandatory.

2. Wait for Ecwid to redirect the user back

Upon authorization, Ecwid redirects the user to the application's redirect_uri specified in request with a code parameter in that URL. The value of this parameter is not an actual token for the store and it must be exchanged for the token at the next step. You can contact us to change the redirect_uri value.

Return URLs example:

# Successfull authorization
https://www.example.com/myapp?code=1234567890

# The user denied to provide access
https://www.example.com/myapp?error=access_denied

If your application is installed on a device (mobile, desktop, etc.) we suggest using a deep link to your app as a redirect_uri. Deep linking allows applications to direct user to a specific page within the application, just like a regular URL on the Internet. Learn more about deep linking and how to enable it in your application.

Return URL parameters:

3. Get an access token

Request

GET https://my.ecwid.com/api/oauth/token?client_id={client_id}&client_secret={client_secret}&code={code}&redirect_uri={redirect_uri}&grant_type=authorization_code

Request example:

https://my.ecwid.com/api/oauth/token?client_id=abcd0123&client_secret=01234567890abcdefg&code=987654321hgfdsa&redirect_uri=https%3A%2F%2Fwww%2Eexample%2Ecom%2Fmyapp&grant_type=authorization_code

Response

Ecwid responds with a JSON-formatted data containing the access token and additional information. The response fields are listed below:

Response example:

{
 "access_token":"12345",
 "token_type":"bearer",
 "scope":"read_store_profile update_catalog",
 "store_id":1003,
 "email": "[email protected]",
 "public_token":"public_qKDUqKkNXzcj9DejkMUqEkYLq2E6BXM9"
}

📘

For security reasons, a temporary code can be exchanged to an access token only once. In case of second attempt, the previously provided access token is automatically disabled.

Notes on user-hosted applications and CMS plugins

Some applications require user to download and install them on their site or device rather than providing a hosted functionality. Some popular examples of such apps are plugins for downloadable CMS like Wordpress, Joomla, Drupal and others. Here is what you should keep in mind when developing such an app:

1. Set up a variable redirect URL.
If your app/plugin is to be downloaded and installed on web sites, then every instance of the app may reside on a different domain. So, a single redirect URL option won't work for you. You will need to enabled support of multiple domains in the redirect_uri parameter. That option implies that:

• Your app will be allowed to specify variable redirect URL in the oAuth requests
• For security reasons, a user will be asked to give access for this app every time an authorization dialog is opened, even if they've already authorized the access to the same app with the same permissions (access scope)
• For security reasons, the redirect URL domain will be always shown in the authorization dialog so the user is aware what website they are authorizing access for

2. Use a special app public key instead of your secret key
As you saw in the documentation above, your app has two keys: the app ID and the app secret key. The former (app ID) is a not secret — you can safely expose it in your code regardless of the kind of the application you're building. The latter — your application secret key — is usually to be kept in secret. However when your app code resides on a user web server or device, the both app keys may be exposed and, whether it's an open source or not, you should assume your app credentials can be found by anyone.

In this case, please contact us and we will enable a special "public mode" for your app secret key, so you may safely expose it in your code. So, if someone find your app keys in your app code, don't worry — the Ecwid API is designed to handle this situation. You app keys won't allow anyone access any user data without user permission (without an access token). Them having your app keys wouldn't put you or your users at risk.

Notes on the public mode of the app keys:

• The API does not change for you if you're using a public key — you keep using the same oAuth flow as described above.
• If your app is distributed as a downloadable plugin, your keys will end up exposed on numerous web servers and being seen by many people. It's OKay — as we stated above, this is expected. The App ID is in general a public thing. The app secret key can be exposed when in public mode.

📘

Contact us if your application is user-hosted and we will configure your application to enable special security measures as described above.