Skip to content
Ideasoft
App Store

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. 1.Merchant→Store admin panel

    Opens the app detail on the Apps page

  2. 2.Store admin panel→Your app

    Opens your app in a frame

    Your Redirect URL with embedded, domain, date, renew_date when present, and hmac.

  3. 3.Your app

    Verifies hmac and date

    Reject the URL if date is not today or yesterday.

  4. 4.Your app→Store admin panel

    Requests authorization if there is no session

    /panel/auth with a state you generate.

  5. 5.Store admin panel→Your app

    Returns with a code

    No consent screen is shown because the app is already installed.

  6. 6.Your app→Store API

    Exchanges the code for tokens

    POST /oauth/v2/token

  7. 7.Your app→Merchant

    Shows its UI inside the panel

Opening URL

Code
GET https://your-app.example.com/ideasoft/callback ?embedded=1 &domain=your-store.myideasoft.com &date=20260518 &renew_date=20270401 &hmac=911c99c9e9da28f884db4fb5c514a9a9861bc9b8558cc3ab7d10f06304a9b393
ParameterDescription
embeddedAlways 1.
domainThe store's domain without the scheme (e.g. your-store.myideasoft.com).
dateThe day the URL was produced, YYYYMMDD (Turkey time).
renew_dateAnnually renewed products only: renewal date, YYYYMMDD.
hmacHMAC-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
hmac = hex( HMAC-SHA256( JSON, client_secret ) ) JSON (without renew_date): {"embedded":"1","domain":"<domain>","date":"<date>"} JSON (with renew_date): {"embedded":"1","domain":"<domain>","date":"<date>","renew_date":"<renew_date>"}
  • As with state verification, the text is PHP json_encode output: fixed key order, no whitespace.
  • embedded is the string "1", not a number.
  • date is 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.
<?php function verifyEmbedded(array $query, string $clientSecret): bool { $data = [ 'embedded' => (string)($query['embedded'] ?? ''), 'domain' => $query['domain'] ?? '', 'date' => $query['date'] ?? '', ]; if (!empty($query['renew_date'])) { $data['renew_date'] = $query['renew_date']; } $expected = hash_hmac('sha256', json_encode($data), $clientSecret); if (!hash_equals($expected, (string)($query['hmac'] ?? ''))) { return false; } $today = new DateTimeImmutable('now', new DateTimeZone('Europe/Istanbul')); $allowed = [$today->format('Ymd'), $today->modify('-1 day')->format('Ymd')]; return in_array($data['date'], $allowed, true); }

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
GET https://your-store.myideasoft.com/panel/auth ?client_id=<client_id> &response_type=code &redirect_uri=<registered redirect_uri> &state=<random value you generate>

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-Policy with frame-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 hmac verification and the authorization flow.
Last modified on