Skip to main content
Embedded apps let you display your own UI inside the OrderProtection merchant dashboard. When a merchant opens your app, it loads in a secure iframe with a session token that provides user and store context — enabling single sign-on without requiring merchants to log in separately.

​
Setting up an embedded app

To enable embedding, configure these settings when creating or editing your app:
  1. Enable Embedded Mode
  2. Set your App URL — the page that will be loaded inside the iframe (e.g., https://yourapp.example.com/embed)
Your App URL must serve a web page that can run inside an iframe.

​
Session token flow

When a merchant opens your embedded app, the following happens:
1

Merchant clicks your app

From their Installed Apps list, the merchant clicks the Open button on your app.
2

OrderProtection generates a session token

The dashboard calls the OrderProtection API to generate a short-lived JWT session token containing the current user’s context.
3

Your app loads in an iframe

Your App URL is loaded in an iframe with the session token appended as a query parameter:
https://yourapp.example.com/embed?session_token=eyJhbGciOiJIUzI1NiIs...
4

Your app extracts the token

Your frontend JavaScript extracts the session_token parameter from the URL:
const params = new URLSearchParams(window.location.search);
const sessionToken = params.get("session_token");
5

Your server verifies the token

Send the session token to the OrderProtection verification endpoint from your server:
curl -X POST https://api.production.orderprotection.com/v1/oauth/session/verify \
  -H "Content-Type: application/json" \
  -d '{
    "session_token": "eyJhbGciOiJIUzI1NiIs..."
  }'
6

Receive user context

The verification endpoint returns the merchant’s identity and store context:
{
  "userId": "cmhdlc5we0001oin850tlbw7y",
  "email": "merchant@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "storeId": "store_abc123",
  "installationId": "inst_xyz789",
  "applicationId": "app_def456",
  "clientId": "op_app_fc6767b5...",
  "scopes": ["read_orders", "read_claims", "read_store"]
}
7

Establish your session

Use the verified context to create a session in your app. The merchant is now signed in — no separate login required.

​
Verification response fields

FieldDescription
userIdThe OrderProtection user ID of the merchant viewing your app
emailThe merchant’s email address
firstNameThe merchant’s first name
lastNameThe merchant’s last name
storeIdThe ID of the store the merchant is currently viewing
installationIdThe ID of this app’s installation on this store
applicationIdYour app’s ID
clientIdYour app’s client ID
scopesArray of scopes the merchant granted to your app

​
Security

​
Token lifetime

Session tokens are valid for 60 seconds. They are designed for a single use — extract the token, verify it immediately, and establish your own session. Do not store or reuse session tokens.

​
Iframe sandboxing

The iframe that loads your app is sandboxed with the following permissions: 
allow-scripts allow-forms allow-same-origin allow-popups
Your app cannot navigate the parent dashboard window (allow-top-navigation is not granted).

​
Rate limiting

The session verification endpoint is rate-limited to 30 requests per minute per IP address.
Use the session token only for the initial handshake. After verification, create your own session (e.g., a cookie or JWT) so that subsequent page loads within the iframe don’t require a new session token.

​
Best practices

  • Verify server-side — Always verify session tokens from your backend, never from client-side JavaScript alone. The verification endpoint validates the token signature and checks that the installation is still active.
  • Handle expiration — If verification returns an error, the token may have expired. Display a message asking the merchant to reload the app.
  • Responsive design — Your embedded page should be responsive, as the iframe adapts to the available dashboard space.
  • No popups for auth — Since the merchant is already authenticated via the session token, avoid redirecting to login pages or showing auth prompts.