Embeds

An embed is the real MGX interface, framed inside your product. Show a grower every live bid on their listings and let them accept, counter, or decline right there; show them their trades; let them talk to a counterparty — the same screens, the same rules, the same trade. You don't rebuild any of it, and you don't send your users to another site to close a deal.

Try it

The panel below is a real embed, framed inside a pretend partner page. Switch between all three with the buttons on the left: accept, counter or decline a bid; open a trade; read and answer a message. Flip the theme, or drop the write scope to see the read-only version. View My Bids opens whichever embed you picked the other way — inside a dialog your page owns.

Watch the counterparty as you go. On the trades embed only a settled trade names one; in messages, an elevator is named but a plain buyer is just “Buyer” until both invoices are paid.

The embed is a mini app, not a set of pop-ups: every step replaces the panel and the header carries a back button, right down to the date picker. Nothing floats over the frame, so nothing can be clipped by a frame whose height your page controls.

Note what accepting and countering ask for: the bid's terms are shown in full, and the seller has to tick an explicit acknowledgement that the deal is binding before the button unlocks. A counter can move the price, the quantity, and the delivery window; anything left alone carries over from the original bid.

How it works

The whole flow exists to keep the grower's access token off the browser.

1. Your user signs in with Login with MGX. You store their access token on your server, as usual.
2. Your page asks your own backend for an embed session.
3. Your backend calls POST /v1/embed/sessions with that token and gets back a URL containing a single-use ticket. The ticket has 120 seconds to be opened.
4. Our loader script puts that URL in an iframe. The framed page spends the ticket once, over POST, and keeps the access token in memory for the life of the frame.
5. The frame talks to you over postMessage — height changes, and an event every time a bid is accepted, countered, or declined.

The token never reaches your page's JavaScript, never lands in a URL, and is never written to browser storage. Reloading the frame starts with no credential at all.

Getting enabled

Embeds are not self-service. An embed is a live accept/decline surface, so MGX turns it on per client along with an allowlist of the origins that may frame it:

• embed_enabled — off by default.
• Embed origins — the exact origins your embed will be framed from, e.g. https://app.example.com. One leading wildcard label is supported: https://*.example.com. These become the page's frame-ancestors policy, so any other site that tries to frame it gets a blank frame.

Contact MGX with your client ID and the origins you need. Each embed also needs its own scopes on the client — see Available embeds. The session endpoint checks the scopes for the embed you ask for, so a client approved for trades but not messages simply cannot open the messages embed.

Step 1: a session endpoint

Add one route to your own backend. It runs as the signed-in user, calls MGX with their token, and returns the response untouched. This is the only place the access token appears.

app.post('/mgx/embed-session', requireLogin, async (req, res) => {
  const response = await fetch('https://api.mygrainexchange.com/v1/embed/sessions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${await mgxTokenFor(req.user)}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      embed: 'bids-received',
      // Trust your own origin, not one the browser sent you.
      origin: 'https://app.example.com',
      theme: req.body.theme === 'dark' ? 'dark' : 'light',
    }),
  })

  res.status(response.status).json(await response.json())
})

Step 2: drop in the loader

Put a placeholder where the bid book should appear, point it at the route you just wrote, and load the script once per page.

<div data-mgx-embed="bids-received"
     data-session-url="/mgx/embed-session"
     data-min-height="240"></div>

<script src="https://dashboard.mygrainexchange.com/embed/mgx-embed.js" async></script>

That's the whole integration. The frame sizes itself, refreshes after every action, and re-mints its own session when one expires.

Or open it in a dialog

For a View My Bids button instead of a panel on the page, put the trigger attributes on any element. The embed opens in a dialog the loader owns, fills it, and scrolls internally — the version to reach for when you don't want to give up page real estate.

<button data-mgx-embed-trigger="bids-received"
        data-session-url="/mgx/embed-session">
  View My Bids
</button>

<script src="https://dashboard.mygrainexchange.com/embed/mgx-embed.js" async></script>

Create an embed session

curl https://api.mygrainexchange.com/v1/embed/sessions \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "embed": "bids-received", "origin": "https://app.example.com", "theme": "light" }'

{
  "data": {
    "embed": "bids-received",
    "url": "https://dashboard.mygrainexchange.com/embed/bids-received?ticket=4DYsFWOi...",
    "expires_in": 120
  }
}

Pass the url straight to the loader — mint one per frame and don't cache it. The ticket is spent the moment a frame opens it, and goes stale after 120 seconds if it isn't. This is not the embed's lifetime: once redeemed, the frame runs on the access token behind it.

Loader reference

Attributes on the placeholder element:

And window.MGXEmbed:

Events

Every handler receives { element, detail } — the placeholder it came from, and the raw message.

MGXEmbed.on('bid.accepted', ({ detail }) => {
  // Mirror the trade into your own system.
  fetch('/mgx/trade-created', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ bidId: detail.bidId, listingId: detail.listingId }),
  })
})

Available embeds

All three run the same mini app: a list, views reached through it, and a back button in the header.

On the bid book, accepting shows the bid's terms — handling fees, delivery window, sample approval, any free-text terms — and requires an explicit "I understand that all bids are binding" acknowledgement, exactly as the MGX dashboard does. Countering asks for the same acknowledgement and lets the seller change price, quantity, and delivery window in one step.

Both display modes work for every embed. Inline, the frame grows and shrinks as the user moves between views; in a dialog, the panel stays put and scrolls.

More embeds are coming. If there's a screen you'd rather frame than rebuild, tell us which one.

Read-only embeds

Leave the write scope off the token and an embed renders without its actions: the bid book loses accept/counter/decline, and messages loses the composer. A live view with nothing a user can accidentally commit to — useful for dashboards, reports, and internal tools. The trades embed is read-only either way.

Security model

Troubleshooting