Embed Nevermined Widgets

If you run a Nevermined organization, you can embed Nevermined-hosted UI flows directly into your site instead of redirecting customers to nevermined.app. Your end-users stay on your domain; the iframe handles auth, payments, and card delegations against the Nevermined backend.

This guide is for organization admins. If you haven’t upgraded to an organization yet, see Platform Partners first.

What you can embed

Checkout

Sell agent plans from your own pricing page. Reports a transaction hash on success.

Card enrollment

Let users add a payment method without leaving your site. Returns the resulting paymentMethodId.

Card delegation

List enrolled cards, create delegations, and revoke either — without redirecting to nevermined.app.

How it works

Your server  →  createInitToken({ userId, orgId, secretKey })
             →  initToken (JWT, valid 5 minutes)

Browser      →  NeverminedWidgets.initialize({ initToken, environment })
             →  exchanges initToken for a session, mounts iframe(s)

Iframe       →  postMessage events: nvm:ready, nvm:success, nvm:error, nvm:close

The widget secret never leaves your server. Your backend mints a short-lived initToken per browser session; the SDK exchanges it for a 2-hour widget session that scopes every API call to a single end-user from your system.

The secretKey is the equivalent of a password for your organization’s widget surface. Anyone who has it can mint tokens that act as any end-user of your org. Keep it in environment variables on a server you control — never commit it, never bundle it into client-side JavaScript.

Setup

Generate a widget key

Open Settings > Organization in the Nevermined App and scroll to the Widget Integration section.

Widget Integration section before any key exists

Click Generate widget key and fill in the dialog:

Name — a descriptive label, e.g. Production website.
Allowed origins — every domain where the widget will be mounted, e.g. https://yourcompany.com and https://staging.yourcompany.com. At least one origin is required. Use Add origin to add more rows. No path, query, fragment, or trailing slash.

The Nevermined backend rejects widget sessions whose parentOrigin doesn’t match this allowlist — it’s your second line of defense if the secret ever leaks. You can edit the list later from the key’s actions menu without rotating the secret.Click Generate key. The raw secret is shown once. Copy it and store it as an environment variable on your server (for example, NVM_WIDGET_SECRET). You won’t see it again.

If you lose the secret, revoke the key from the dashboard and generate a new one. There’s no recovery path — that’s by design.

Mint the initToken on your server

Install the server SDK on your backend and expose a small endpoint that signs an initToken for the currently logged-in end-user.

npm install @nevermined-io/ui-widgets-server

The call is the same regardless of framework:

import { createInitToken } from '@nevermined-io/ui-widgets-server'

const initToken = await createInitToken({
  userId: '<the end-user id from your system>',
  orgId: '<your org id from the dashboard>',
  secretKey: process.env.NVM_WIDGET_SECRET!,
})

Pick the framework that matches your stack:

Vite middleware
Express
Next.js Route Handler

// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    {
      name: 'nvm-init-token',
      configureServer(server) {
        server.middlewares.use('/api/init-token', async (req, res) => {
          const { createInitToken } = await import('@nevermined-io/ui-widgets-server')
          const initToken = await createInitToken({
            userId: req.headers['x-user-id'] as string, // resolve from your auth
            orgId: process.env.NVM_ORG_ID!,
            secretKey: process.env.NVM_WIDGET_SECRET!,
          })
          res.setHeader('content-type', 'application/json')
          res.end(JSON.stringify({ initToken, environment: 'sandbox' }))
        })
      },
    },
  ],
})

import express from 'express'
import { createInitToken } from '@nevermined-io/ui-widgets-server'

const app = express()

app.get('/api/init-token', async (req, res) => {
  const initToken = await createInitToken({
    userId: req.user!.id, // from your auth middleware
    orgId: process.env.NVM_ORG_ID!,
    secretKey: process.env.NVM_WIDGET_SECRET!,
  })
  res.json({ initToken, environment: 'sandbox' })
})

// app/api/init-token/route.ts
import { NextResponse } from 'next/server'
import { createInitToken } from '@nevermined-io/ui-widgets-server'
import { auth } from '@/lib/auth'

export async function GET() {
  const session = await auth()
  if (!session?.user?.id) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }
  const initToken = await createInitToken({
    userId: session.user.id,
    orgId: process.env.NVM_ORG_ID!,
    secretKey: process.env.NVM_WIDGET_SECRET!,
  })
  return NextResponse.json({ initToken, environment: 'sandbox' })
}

userId identifies the end-user of your site, not the org admin. Resolve it from your auth session — Nevermined uses it as the sub of the session JWT to scope every widget action to that user.

Mount the widget in the browser

Install the browser SDK on your frontend.

npm install @nevermined-io/ui-widgets

Fetch the initToken from your endpoint and initialize the SDK. The same nvm instance can mount any of the available widgets.

import { NeverminedWidgets } from '@nevermined-io/ui-widgets'

const { initToken, environment } = await fetch('/api/init-token').then(r => r.json())
const nvm = await NeverminedWidgets.initialize({ initToken, environment })

Then mount whichever widget you need into a container element on your page:

Checkout
Enroll a card
List & delegate

nvm.checkout.start({
  did: 'did:nv:<your-agent-did>',
  // planId is optional; omit to show the plan carousel
  container: document.getElementById('checkout-widget')!,
  onReady: () => console.log('Widget rendered'),
  onSuccess: ({ did, planId, txHash }) => {
    console.log('Purchase complete', { did, planId, txHash })
  },
  onError: (err) => console.error('Checkout failed', err),
  onClose: () => console.log('User closed the widget'),
})

nvm.delegations.enrollCard({
  container: document.getElementById('enroll-widget')!,
  onSuccess: ({ paymentMethodId }) => {
    console.log('Card enrolled', paymentMethodId)
  },
  onError: (err) => console.error('Enrollment failed', err),
})

nvm.delegations.listCards({
  container: document.getElementById('cards-widget')!,
  onCardAction: ({ action, paymentMethodId }) => {
    if (action === 'delegate') {
      nvm.delegations.createDelegation({
        paymentMethodId,
        container: document.getElementById('cards-widget')!,
        onSuccess: ({ delegationId }) => console.log('Delegated', delegationId),
      })
    }
  },
})

Available widgets

Method	Mounts iframe	Result
`nvm.checkout.start({ did, planId?, container, ... })`	yes	`onSuccess`: `{ did, planId, txHash }`
`nvm.delegations.enrollCard({ container, ... })`	yes	`onSuccess`: `{ paymentMethodId }`
`nvm.delegations.listCards({ container, onCardAction, ... })`	yes	`onCardAction`: `{ action: 'delegate', paymentMethodId }`
`nvm.delegations.createDelegation({ paymentMethodId, container, ... })`	yes	`onSuccess`: `{ delegationId, paymentMethodId }`
`await nvm.delegations.revokeCard(paymentMethodId)`	no — direct API call	resolves on 2xx
`await nvm.delegations.revokeDelegation(delegationId)`	no — direct API call	resolves on 2xx

All iframe-mounting methods share the same lifecycle:

Callback	When
`onBooted`	iframe DOM mounted (auth not yet validated)
`onReady`	session validated, widget interactive
`onSuccess`	terminal success — widget destroys itself
`onError`	terminal error — widget destroys itself
`onClose`	user closed the widget — instance destroyed

Once a widget instance fires onSuccess, onError, or onClose, it’s terminal: calling its method again throws. Construct a fresh widget via the same nvm instance to mount another flow.

Environments

Pick the environment that matches the Nevermined dashboard you used to mint the widget key.

Environment	API base	Webapp base	When to use
`sandbox`	`https://api.sandbox.nevermined.app`	`https://nevermined.app`	Testing on Base Sepolia with sandbox credentials
`live`	`https://api.live.nevermined.app`	`https://nevermined.app`	Production on Base mainnet

Production checklist

Server-side secrets only

Keep NVM_WIDGET_SECRET in your runtime env vars. Never commit it, never ship it to the browser, never put it in NEXT_PUBLIC_* or VITE_* variables.

Allowed origins populated

Add every domain where you mount the widget. The backend rejects sessions from any other origin.

HTTPS only

Serve both your site and your initToken endpoint over HTTPS in production. parentOrigin includes the scheme, so origins must match exactly.

Real userId per session

Pass the actual end-user identifier from your auth — never a placeholder, never the same value for every visitor.

Rotate on suspicion

If the secret might have leaked, revoke the key from the dashboard and generate a new one. Update your env var and redeploy.

Short token TTLs

Default initToken expiry is 5 minutes — leave it. Don’t cache the token server-side.

Troubleshooting

Symptom	Cause	Fix
`onError`: `UNAUTHORIZED`, apiCode `BCK.WIDGET_SESSION.0001`	initToken expired or signed with a wrong/revoked secret	Mint a fresh token; verify your secret matches the active key in the dashboard
`onError`: `UNAUTHORIZED`, apiCode `BCK.WIDGET_SESSION.0002`	The org has no active widget keys	Generate one in the dashboard
`onError`: `UNAUTHORIZED`, apiCode `BCK.WIDGET_SESSION.0005`	Session token expired (default 2h)	The SDK auto-refreshes; if it fails persistently, re-fetch the initToken from your server
`onError`: `UNAUTHORIZED`, apiCode `BCK.WIDGET_SESSION.0007`	initToken missing `orgId` or `wallet` claim	Upgrade `@nevermined-io/ui-widgets-server` to the latest version
`onError`: `UNAUTHORIZED`, apiCode `BCK.WIDGET_SESSION.0011`	The widget key was revoked while the session was alive	Mint a new `initToken` with the new key
`onError`: `NETWORK`	Fetch failed before getting a response	Check your network, CORS, and that the `environment` matches the API you minted the key against
Widget mounts but never fires `onReady`	`parentOrigin` doesn’t match `allowedOrigins`	Add your site’s origin to the key’s allowlist (mind the scheme: `https://` vs `http://`)
`[NeverminedWidgets] initialize: invalid environment`	`environment` is not a supported value	Use `'sandbox'` or `'live'`

Platform Partners

Background on Nevermined organizations and how to upgrade your account.

Card enrollment

How Nevermined card enrollment works under the hood — the widget surfaces this same flow.

Learn

Build

Nevermined Pay

Solutions

Integrations

Payment Patterns

Components

Specs

FAQ

What you can embed

Checkout

Card enrollment

Card delegation

How it works

Setup

Available widgets

Environments

Production checklist

Server-side secrets only

Allowed origins populated

HTTPS only

Real userId per session

Rotate on suspicion

Short token TTLs

Troubleshooting

Platform Partners

Card enrollment

Learn

Build

Nevermined Pay

Solutions

Integrations

Payment Patterns

Components

Specs

FAQ

Documentation Index

​What you can embed

Checkout

Card enrollment

Card delegation

​How it works

​Setup

​Available widgets

​Environments

​Production checklist

Server-side secrets only

Allowed origins populated

HTTPS only

Real userId per session

Rotate on suspicion

Short token TTLs

​Troubleshooting

​Related

Platform Partners

Card enrollment

What you can embed

How it works

Setup

Available widgets

Environments

Production checklist

Troubleshooting

Related