Installation and Authorization
The same flow runs when a merchant installs your app from the App Store, clicks Go to app in the App Store, or opens it from the Apps list in the store admin panel:
- 1.Merchant→App Store
Installs or buys the app
For paid apps, payment is taken first.
- 2.App Store→Store admin panel
Redirects to the store's authorization page
https://<store>/panel/authwithclient_id,redirect_uriand astatesigned by Ideasoft. - 3.Store admin panel→Merchant
Shows the consent screen
On first install only. If the app was approved before, this step is skipped.
- 4.Merchant→Store admin panel
Approves the permissions
- 5.Store admin panel→Your app
Redirects to your Redirect URL
With
state,code,domain,user_idand, when present,renew_date. - 6.Your app
Verifies the state signature
If verification fails, stop the flow and do not request tokens.
- 7.Your app→Store API
Exchanges the code for tokens
POST /oauth/v2/token, within 30 seconds of receiving thecode. - 8.Store API→Your app
Returns the tokens
access_tokenis valid for 24 hours; renew it withrefresh_tokenbefore it expires. - 9.Your app→Store API
Calls the Admin API
With the
Authorization: Bearer <access_token>header.
Later openings run the same flow: the consent screen is skipped and a new code arrives every time.
Parameters sent to your Redirect URL
Code
| Parameter | Description |
|---|---|
state | A 64-character hexadecimal HMAC-SHA256 signature used to verify that the request comes from Ideasoft (below). |
code | Single-use authorization code for obtaining tokens. Valid for 30 seconds. |
domain | The address of the store that installed or opened the app, including the scheme, e.g. https://your-store.myideasoft.com. URL-encoded. |
user_id | ID of the admin panel user who performed the action. Not covered by the signature. |
renew_date | Annually renewed products only: renewal date, YYYYMMDD (Renewal date). |
If the merchant denies access, the redirect carries error parameters instead of a code:
Code
Verifying state
state is the HMAC-SHA256 signature, keyed with your Client Secret, of a JSON text built from the store address and the date:
Code
The signed text is PHP json_encode output. When reproducing it in your language:
- Key order is fixed:
domain,date,renew_date. - The text contains no whitespace.
/is written as\/:"https:\/\/your-store.myideasoft.com". JavaScript'sJSON.stringifyand Python'sjson.dumpsdo not do this; use the helper in the examples below.dateis the day the signature was produced (Turkey time). It is not sent in the URL; try today and yesterday to cover midnight.- Add
renew_dateonly when it is present in the URL. - Compare in constant time (
hash_equals,timingSafeEqual,compare_digest).
Do not request tokens before state is verified.
Test vector
Use these values to check your implementation:
| Input | Value |
|---|---|
client_secret | example-client-secret |
domain | https://your-store.myideasoft.com |
date | 20260518 |
| Signed text | {"domain":"https:\/\/your-store.myideasoft.com","date":"20260518"} |
state | ecde6d7136bde13cf3630938b69f40cb556b7f6f9dfefd22ac703902ca5f2a9d |
state with renew_date=20270401 | 2f2ee2d51b778a3b7060f01227efd140630c2ad56927f665671c5350b1bf258b |
Obtaining tokens
After state is verified, exchange the code for tokens within 30 seconds. Send the request to the store given in the domain parameter:
Code
The returned access_token is valid for 24 hours. Renew it with the refresh_token before it expires; the refresh token changes on every renewal. For the full request and response, error codes and the refresh request, see Authentication.
Send client_secret in the request body, never in the URL.
Identifying the store and the user
- Identify the store by the
domainparameter. Becausedomainis part of thestatesignature, it can be trusted after verification. Store your tokens per store. user_idis not signed; do not use it on its own as proof of identity or authorization.- Every opening delivers a new
code. If you already hold valid tokens for the store you do not have to request new ones, but verifystateon every opening.
Renewal date (renew_date)
For products sold with annual renewal on the App Store, the renewal date is added to the Redirect URL as renew_date in YYYYMMDD format (e.g. renew_date=20270401). When present, renew_date is also part of the state signature.
May be missing on first install
When an app is first installed from the App Store, the renewal date may not exist yet; in that case renew_date is not sent. It is sent on the user's later openings of the app.