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 for your app) 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 at [email protected] 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) |
| user_id | ID of a user |
| admin_sso | Admin_SSO object |
Store owner's accountEmail, as provided in Store profile | |
| profile_scopes | The list of scopes that are granted automatically according to the assigned staff scopes. Divided by space character. See: Get staff scopes |
| public_token | Public token. Provided if requested access scopes contain public_storefront scope. |
Admin_SSO
| Field | Description |
|---|---|
| role | The role of account that receives a token. For example, STORE_OWNER |
Response example:
{
"access_token":"12345",
"token_type":"bearer",
"scope":"read_store_profile update_catalog",
"store_id":1003,
"user_id": 42722912,
"admin_sso": {
"role": "STORE_OWNER"
},
"email": "[email protected]",
"profile_scopes": "read_store_profile read_store_profile_extended update_store_profile update_own_user_profile charge get_shipping_labels create_orders update_orders read_orders create_catalog update_catalog read_catalog add_to_cp update_discount_coupons create_discount_coupons read_discount_coupons create_customers update_customers read_customers customize_storefront allow_sso create_stores read_stores add_shipping_method add_payment_method customize_cart_calculation clone_stores public_storefront read_invoices delete_invoices create_invoices read_invoices_template update_invoices_template read_subscriptions update_subscriptions read_applications access_support_chat update_store_profile_verify_email read_tax_rates_dictionary update_store_profile_auth buy_domains read_store_stats read_checkouts create_checkouts update_checkouts access_billing delete_store develop_apps read_staff invite_staff create_staff update_staff delete_staff ads_management mailchimp_mailing triggered_emails_management analytics_tools_report_management manage_instant_site read_dashboard_reports automatic_discounts_management sell_on_your_website sell_on_fb sell_on_tiktok sell_on_mobile sell_on_pos sell_on_shopapp sell_on_google_shopping sell_on_marketplaces create_promotion read_promotion update_promotion delete_promotion read_site_redirects update_site_redirects create_site_redirects read_store_limits",
"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.