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:
- Your app sends the user to the Ecwid authorization dialog.
- 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.
- 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}
Parameter | Required | Description |
---|---|---|
client_id | required | Application ID |
redirect_uri | required | URI in your app where users will be sent after authorization. It must match the domain/URL of the registered return_url specified in the app settings (contact us to set or change it). I.e. if the registered return_url is http://www.example.com , the redirect_uri in request might be http://www.example.com/oauth/callback.php , but not http://www.example2.com/ |
response_type | required | code (must always be code ) |
scope | required | Scope of access that your app requests from the user, separated by space. See all possible values in Access scopes section |
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:
Parameter | Description |
---|---|
code | If the user successfully authorizes the application, the query will contain the code parameter. That is a temporary code that your app should exchange to an access token. This code can be used only once and lives for a few minutes so your app should request the token as soon as it gets the code. See the Authorization step #3 for the details. |
error | If the user does not allow authorization to the application, query parameters indicate the user canceled authorization in error field |
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
Parameter | Required | Description |
---|---|---|
client_id | required | Application ID. This is a public key. |
client_secret | required | Application secret key. Note: regularly, this must not be exposed. But a special app public key can also be used here when the app code is publicly available and credentials cannot be hidden (e.g. a downloadable CMS plugin). See notes at the end of this part for more details on user-hosted applications. |
code | required | The temporary code received on the step #2 |
redirect_uri | conditional | If the redirect_uri parameter was included in the authorization request, you must include it in the token request and their values must be identical. |
grant_type | required | Must be 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:
Field | Description |
---|---|
access_token | Private authorization token. This is a key your app will use to access Ecwid API on behalf of the user. |
token_type | bearer (it's always bearer ) |
scope | List of permissions (API access levels) given to the app, separated by space. See all possible values in Access scopes |
store_id | Ecwid store ID (a unique Ecwid account identificator) |
Store owner's accountEmail , as provided in Store profile | |
public_token | Public token. Provided if requested access scopes contain public_storefront scope. |
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.