Overview
External applications could also be installed/connected to a user store outside the Ecwid App Market (even if they are listed in the Ecwid App Market as well), and therefore installation can be initiated from an external page. In that case, application must be able to handle the complete oAuth flow. Find its description below.
Getting an access token
Retrieving an access token in a complete oAuth flow includes the following steps:
- Your application sends users to Ecwid authorization (login) dialog.
- Upon authorization, Ecwid redirects them to the app redirectUrl (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 redirectUrl specified in the app settings (contact us at [email protected] to set or change it). I.e. if the registered redirectUrl is http://www.example.com, 'redirect_uri' in request might be http://www.example.com/oauth/callback.php, but not http://www.example2.com/ |
| response_type | required | Always 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.
redirectUrl 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.
redirectUrl parameters:
| Parameter | Description |
|---|---|
| code | In case of successful authorization, the query contains the code parameter. That is a temporary code that should be exchanged for an access token by your app. 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 step #2 for the details. |
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. Only client_id can be shown inside publicly available code. See notes at the end of this part for more details on user-hosted applications. |
| code | required | The temporary code received in 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 JSON-formatted data containing the access token and additional information. The response fields are listed below:
| Field | Description |
|---|---|
| access_token | Secret access token. This is a token your app will use to access Ecwid REST API on behalf of the user. |
| token_type | 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 identification) |
| user_id | ID of a specific store user (e.g. admin, staff, etc.) |
| admin_sso | Admin_SSO object |
Store owner's accountEmail, as 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 only 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 users 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 redirectUrl
If your app/plugin is to be downloaded and installed on websites, then every instance of the app may reside on a different domain. So, a single redirectUrl option won't work for you. In that case, ask us ([email protected]) to enable support for 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 access to the same app with the same permissions (scopes)
- For security reasons, redirectUrl domain will be always shown in the authorization dialog so users are 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 (client_id) and the app secret key (client_secret). App's client_id isn't secret — you can safely expose it in your code regardless of the kind of the application you're building. client_secret however be kept in secret. When your app code resides on a user web server or device, 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, so you may safely expose it in your code. In that case, if someone finds your app keys in app code, you don't need to worry — our API is designed to safely handle this situation. App keys won't allow anyone to access any user data without user permission (access token). Having your app keys wouldn't put you or your users data 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, however this is expected behavior. client_id is a public entity and client_secret can be exposed 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.