Authentication
EasyStore Apps authenticate with OAuth 2.0 (Authorization Code Grant). When a merchant installs your app, your app gets an access token for that store, and sends it with every API request.
📖 This page is a quick reference. For the full step-by-step guide with diagrams, code and test values, see Develop app: App installation.
Credentials
Create an app in the Partner Dashboard to get its Client ID and Client secret. Keep the Client secret on your server only. It is used to get access tokens and to verify every request EasyStore sends you.
OAuth flow at a glance
| Step | Request | Details |
|---|---|---|
| 1. EasyStore opens your App URL | GET {App URL}?shop=...&host_url=...×tamp=...&hmac=... |
Installation steps 1–3 |
| 2. Your app asks for permission | {host_url}/oauth/authorize?client_id=...&scope=...&redirect_uri=... |
Installation step 4, scopes |
| 3. EasyStore redirects back | GET {redirect_uri}?code=...&shop=...&host_url=...×tamp=...&hmac=... |
Installation step 6 |
| 4. Your app gets the access token | POST https://{shop}/api/3.0/oauth/access_token.json with code,
client_id, client_secret (JSON body) |
Installation steps 7–8 |
The authorization code is valid for 5 minutes and can be exchanged only once. The access token stays valid until the merchant uninstalls your app.
Making authenticated requests
Send the access token in the EasyStore-Access-Token header with every API request:
curl 'https://{shop}/api/3.0/products.json' \
--header 'EasyStore-Access-Token: {access_token}'
The token can only access the scopes the merchant approved. See Calling the API and Popular APIs.
Security checks
Before trusting any request from EasyStore, your app must:
- Verify the
hmacparameter (or theEasystore-Hmac-Sha256header for webhooks). See Request HMAC verification and Webhook HMAC verification. - Check that
shopis a valid hostname ending with.easy.co. Your app sends its Client secret tohttps://{shop}, so never trust an unchecked value. - Reject requests whose
timestampis too old, to prevent replays.