Embedded Apps
Apps registered as embedded open in a frame (iframe) on the app page of the store admin panel. In this case the panel does not go through the authorization URL; it opens your Redirect URL directly with signed parameters, and your app starts its own authorization request if needed after verifying the store.
- 1.Merchant→Store admin panel
Opens the app detail on the Apps page
- 2.Store admin panel→Your app
Opens your app in a frame
Your Redirect URL with
embedded,domain,date,renew_datewhen present, andhmac. - 3.Your app
Verifies hmac and date
Reject the URL if
dateis not today or yesterday. - 4.Your app→Store admin panel
Requests authorization if there is no session
/panel/authwith astateyou generate. - 5.Store admin panel→Your app
Returns with a code
No consent screen is shown because the app is already installed.
- 6.Your app→Store API
Exchanges the code for tokens
POST /oauth/v2/token - 7.Your app→Merchant
Shows its UI inside the panel
Opening URL
Code
| Parameter | Description |
|---|---|
embedded | Always 1. |
domain | The store's domain without the scheme (e.g. your-store.myideasoft.com). |
date | The day the URL was produced, YYYYMMDD (Turkey time). |
renew_date | Annually renewed products only: renewal date, YYYYMMDD. |
hmac | HMAC-SHA256 signature of the parameters above. |
The Redirect URL must not contain a query string
The panel appends these parameters to your Redirect URL with ?. If your registered URL already contains ?, the opening URL breaks.
Verifying hmac
Code
- As with state verification, the text is PHP
json_encodeoutput: fixed key order, no whitespace. embeddedis the string"1", not a number.dateis sent in the URL; compute the signature with that value, then check that the date is today or yesterday. Reject older URLs.- Compare in constant time.
Test vector: for client_secret=example-client-secret, domain=your-store.myideasoft.com and date=20260518 (no renew_date) the signed text is {"embedded":"1","domain":"your-store.myideasoft.com","date":"20260518"} and hmac is 911c99c9e9da28f884db4fb5c514a9a9861bc9b8558cc3ab7d10f06304a9b393.
hmac is not a session
hmac only signs the store and the day, so it can be reused within the same day. Do not treat it as a persistent session or as API authorization, and do not write it to logs. Complete the authorization below to access store data.
Authorization
If you have no valid session or tokens for this store, redirect from within the frame to the store's authorization URL with a state value you generate:
Code
Because the app is already installed on the store, no consent screen is shown; the store returns to your Redirect URL with state, code, domain and user_id. In this flow state is the value you sent, not an Ideasoft signature; compare it with the value you stored. Then exchange the code for tokens.
Running inside a frame
- Your app opens in a frame inside the store admin panel. Frame-blocking headers (
X-Frame-Options,Content-Security-Policywithframe-ancestors) must allow store domains to display your app. - Browsers may restrict third-party cookies inside frames. Do not tie your session to cookies alone; design it so it can be re-established on every opening through
hmacverification and the authorization flow.