Native apps
Native applications work in a separate tab in Ecwid Control Panel. After users install an application, Ecwid redirects them to the new tab. At the same time, iframeUrl of the app receives a request with an encoded 'payload' parameter. Payload must be decoded to get an access token, store ID, and language, which are used to interact with the store on behalf of the user. Find details on the flow here: Authentication in native apps
See native apps documentation to start working on the application.
External apps
Retrieving an access token for external apps includes the following steps:
- When users install the app, Ecwid redirects them to the redirectUrl with an additional temporary code parameter. Reach out to us at [email protected] to set or change it for your app.
- Your code exchanges temporary code for an access token from Ecwid in the background. This token can be used in REST API calls.
User needs to go through all these steps only once in order for your app to get and store access token for that user. Token will be used in any call you make to Ecwid API on behalf of the user.
1. Merchant is redirected
redirectUrl example:
# Successfull authorization
https://www.example.com/myapp?code=1234567890
Upon successful installation, Ecwid redirects the user to the application's redirectUrl (redirect_uri parameter) with an additional code parameter in the URL (reach out to us at [email protected] to set or change it). The value of this parameter is not an actual token for the store and it must be exchanged for the token in the next step of the process.
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. |
| error | If user authorization fails, query parameters indicate the user canceled authorization in error message |
2. Get access token
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
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 |
| client_secret | required | Application secret key |
| code | required | The temporary code received on the step #1 |
| redirect_uri | required | redirectUrl of your application. Reach out to us at [email protected] to set or change it |
| grant_type | required | Always must be authorization_code |
Response example:
{
"access_token":"secure_123453lasdADSKasasdjasdklasASkmns",
"token_type":"bearer",
"scope":"read_store_profile update_catalog",
"store_id":1003,
"public_token":"public_qKDUqKkNXzcj9DejkMUqEkYLq2E6BXM9"
}
Ecwid responds with JSON-formatted data containing the access token and additional information. Response fields are listed below:
| Field | Description |
|---|---|
| access_token | Secret access token (secret_token). Your app will use it to access Ecwid REST API on behalf of the user. |
| token_type | Always bearer |
| scope | List of permissions (API access scopes) given to the app, separated by space. See all possible values in Access scopes |
| store_id | Ecwid store ID (a unique Ecwid account identification) |
| public_token | Access tokens. Provided if requested access scopes contain public_storefront scope. |
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.