Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nevermined.app/llms.txt

Use this file to discover all available pages before exploring further.

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 an agent’s plans — or a standalone plan with no agent — from your own pricing page.

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  →  createWidgetSession({ email, orgId, rawSecret, apiBaseUrl })
             →  WidgetSession (2-hour JWT + bearer credential)

Browser      →  NeverminedWidgets.initialize({ session, environment })
             →  mounts iframe(s) directly — no token-exchange call

Iframe       →  postMessage events: nvm:ready, nvm:success, nvm:error, nvm:close
The widget secret never leaves your server. The integrator backend POSTs { email, orgId, rawSecret } to the Nevermined API server-to-server; the API hashes the candidate and constant-time compares against the SHA-256 of the keys you generated in the dashboard, then returns a 2-hour WidgetSession your backend forwards verbatim to the browser SDK.
The rawSecret is the equivalent of a password for your organization’s widget surface. Anyone who has it can mint sessions 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. The API only ever stores its SHA-256; if you lose the raw value, revoke the key in the dashboard and generate a new one.

Setup

1

Generate a widget key

Open Settings > Organization in the Nevermined App and scroll to the Widget Integration section.Widget Integration section before any key existsClick 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. Generate widget key dialog with name and allowed origins
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.Widget secret shown once after creation
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.
2

Mint the widget session on your server

Install the server SDK on your backend and expose a small endpoint that mints a WidgetSession for the currently logged-in end-user.
npm install @nevermined-io/ui-widgets-server
The call is the same regardless of framework:
import { createWidgetSession } from '@nevermined-io/ui-widgets-server'

const session = await createWidgetSession({
  email: '<the end-user email from your system>',
  orgId: '<your org id from the dashboard>',
  rawSecret: process.env.NVM_WIDGET_SECRET!,
  apiBaseUrl: 'https://api.sandbox.nevermined.app', // or live URL
})
Pick the framework that matches your stack:
// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    {
      name: 'nvm-widget-session',
      configureServer(server) {
        // POST-only: the response carries a bearer credential, so
        // the endpoint must not be cacheable / prefetch-friendly.
        server.middlewares.use('/api/widget-session', async (req, res) => {
          if (req.method !== 'POST') {
            res.statusCode = 405
            res.setHeader('allow', 'POST')
            res.end()
            return
          }
          const { createWidgetSession } = await import('@nevermined-io/ui-widgets-server')
          const session = await createWidgetSession({
            email: req.headers['x-user-email'] as string, // resolve from your auth
            orgId: process.env.NVM_ORG_ID!,
            rawSecret: process.env.NVM_WIDGET_SECRET!,
            apiBaseUrl: process.env.NVM_API_BASE_URL!,
          })
          res.setHeader('content-type', 'application/json')
          res.setHeader('cache-control', 'no-store')
          res.end(JSON.stringify({ session, environment: 'sandbox' }))
        })
      },
    },
  ],
})
email identifies the end-user of your site, not the org admin. Resolve it from your auth session — Nevermined uses it as the canonical identity for the widget user (the same email logging in directly at nevermined.app resolves to the same Privy user, wallet and profile).
3

Mount the widget in the browser

Install the browser SDK on your frontend.
npm install @nevermined-io/ui-widgets
Fetch the session from your endpoint with a POST (the server side mints a bearer credential — GET would risk caching/prefetching it) and pass it straight to the SDK. The same nvm instance can mount any of the available widgets.
import { NeverminedWidgets } from '@nevermined-io/ui-widgets'

const { session, environment } = await fetch('/api/widget-session', {
  method: 'POST',
  credentials: 'same-origin', // forward your app's auth cookies
}).then((r) => r.json())
const nvm = await NeverminedWidgets.initialize({ session, environment })
Then mount whichever widget you need into a container element on your page:Each onSuccess receives a single event object: event.result holds the flow’s result fields and event.handle.close() dismisses the iframe. The widget stays mounted on success (showing its success state) until you call handle.close() — there is no auto-dismiss.
Sell a specific agent’s plans. Pass the agent did; planId is optional — omit it to show the plan carousel.
nvm.checkout.start({
  did: 'did:nv:<your-agent-did>',
  planId: 'plan-<optional>', // omit to show the plan carousel
  container: document.getElementById('checkout-widget')!,
  onReady: () => console.log('Widget rendered'),
  onSuccess: ({ result, handle }) => {
    // result: { did: string; planId?: string; txHash?: string }
    console.log('Purchase complete', result)
    handle.close() // dismiss when your post-purchase UI is ready
  },
  onError: (err) => console.error('Checkout failed', err),
  onClose: () => console.log('User closed the widget'),
})
Every iframe-mounting method also accepts optional width / height (pixels) for inline sizing — the SDK clamps them to a supported range; omit them for the default overlay. Checkout, enroll, and list also accept onAuthMismatch / onAuthSwitchRequest for the multi-org identity case — see Handling identity mismatches.

Available widgets

MethodMounts iframeResult
nvm.checkout.start({ did, planId?, container, ... })yesonSuccessevent.result: { did, planId?, txHash? }
nvm.checkout.startPlan({ planId, container, ... })yesonSuccessevent.result: { planId, txHash? }
nvm.delegations.enrollCard({ container, provider?, ... })yesonSuccessevent.result: { paymentMethodId }
nvm.delegations.listCards({ container, onCardAction, ... })yesonCardAction: { action: 'delegate' | 'revoked', paymentMethodId }
nvm.delegations.createDelegation({ paymentMethodId, container, ... })yesonSuccessevent.result: { delegationId, paymentMethodId }
await nvm.delegations.revokeCard(paymentMethodId)no — direct API callresolves on 2xx
await nvm.delegations.revokeDelegation(delegationId)no — direct API callresolves on 2xx
All iframe-mounting methods share the same lifecycle:
CallbackWhen
onBootediframe DOM mounted (auth not yet validated)
onReadysession validated, widget interactive
onSuccess(event)flow succeeded — the widget stays mounted in its success state; call event.handle.close() to dismiss it
onErrorterminal error — widget destroys itself
onClosewidget dismissed (the user closed it, or you called event.handle.close()) — instance destroyed
A widget instance is single-use. Once it reaches a terminal state — you call event.handle.close() after success, or it fires onError / onClose — calling its method again throws. Construct a fresh widget via the same nvm instance to mount another flow.

Redirect / CLI mode (no iframe)

For integrations that aren’t an in-page iframe — a CLI tool, or any flow where you’d rather hand the user to a full-page Nevermined screen and get them back via a callback — open the embed route as a top-level browser navigation instead of mounting it through the SDK. You pass a sessionToken and a returnUrl on the query string. The page runs the same flow and, on success, redirects the browser to returnUrl with the result IDs (plus your state echo) appended as query parameters — the same shape as an OAuth callback. Supported on the card flows and plan-only checkout. The agent checkout (/embed/checkout/$did) is iframe-only.
RouteResult params appended to returnUrl
/embed/cards/setuppaymentMethodId, delegationId
/embed/cards/enrollpaymentMethodId
/embed/cards/delegatedelegationId
/embed/checkout/plan/<planId>planId, paymentIntent

Minting a session for redirect mode

  • CLI / logged-in Nevermined userPOST {apiBaseUrl}/api/v1/widgets/session/self with the user’s Nevermined credential and the orgId (the user must be a member of the org). Self-mint sessions only accept localhost returnUrls — the CLI listens on a local port.
  • Hosted site — mint with the same server-side createWidgetSession as the iframe flow; the returnUrl must belong to the widget key’s allowedOrigins.

Example

https://nevermined.app/embed/cards/setup
  ?sessionToken=<the WidgetSession token>
  &returnUrl=http://localhost:8976/callback
  &state=<opaque csrf value>
On success the browser lands on:
http://localhost:8976/callback?paymentMethodId=pm_...&delegationId=del_...&state=<your csrf value>
returnUrl must be an absolute http(s) URL and is re-validated server-side against the session’s allow-list — localhost for self-mint sessions, the widget key’s allowedOrigins otherwise. A URL that isn’t allowed refuses to mount, so result IDs are never sent to an unapproved destination.

Handling identity mismatches

A widget session is minted for a specific email (the end-user you passed to createWidgetSession). If the host browser already has a Nevermined (Privy) login for a different email, the iframe detects the mismatch and:
  • fires onAuthMismatch(detail)detail carries the expected vs. host emails, and the iframe shows an in-place prompt (mirror it in your own UI if you want);
  • if the user chooses “Continue as <host email>”, fires onAuthSwitchRequest(detail) — re-mint a widget session bound to detail.requestedEmail (call your session endpoint again with that email) and reopen the widget.
If the browser has no Nevermined login there’s no mismatch, and the widget proceeds against the session’s email.

Environments

Pick the environment that matches the Nevermined dashboard you used to mint the widget key.
EnvironmentAPI baseWebapp baseWhen to use
sandboxhttps://api.sandbox.nevermined.apphttps://nevermined.appTesting on Base Sepolia with sandbox credentials
livehttps://api.live.nevermined.apphttps://nevermined.appProduction 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 widget-session endpoint over HTTPS in production. parentOrigin includes the scheme, so origins must match exactly.

Real email per session

Pass the actual end-user email from your auth — never a placeholder, never the same value for every visitor. It’s the canonical identity used across Nevermined.

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. The API only ever stores its SHA-256, so the only recovery path is rotation.

Short session TTLs

Widget sessions expire after 2 hours; the SDK auto-refreshes them in-place. Don’t cache or share session objects across users.

Troubleshooting

SymptomCauseFix
onError: UNAUTHORIZED, apiCode BCK.WIDGET_SESSION.0001rawSecret doesn’t match any active key for the org — or the org has no active key at all (one code covers both cases, by design, so attackers can’t probe which)Confirm the secret in your env matches an active key in the dashboard; generate one if the org has none; rotate if leaked
onError: UNAUTHORIZED, apiCode BCK.WIDGET_SESSION.0005Session token expired (default 2h)The SDK auto-refreshes; if it fails persistently, re-fetch a fresh session from your server
onError: UNAUTHORIZED, apiCode BCK.WIDGET_SESSION.0011The widget key was revoked while the session was aliveRe-call createWidgetSession with the new key’s rawSecret
Widget mounts but never reaches onReadyonError apiCode BCK.WIDGET_SESSION.0012 (403)The mount origin isn’t in the key’s allowedOriginsAdd your site’s origin to the key’s allowlist (mind the scheme: https:// vs http://)
onError: UNAUTHORIZED, apiCode BCK.WIDGET_SESSION.0020 (403)The did / planId you’re checking out belongs to a different organization than the widget sessionEmbed only agents/plans owned by the org the session was minted for
onError: PAYMENT_NOT_CONFIRMEDCame back from a Stripe redirect, but the backend couldn’t confirm the payment intentDon’t trust the redirect_status query flag alone; if the user was actually charged, reconcile via your Stripe dashboard / support
onError: NETWORKFetch failed before getting a responseCheck your network, CORS, and that the environment matches the API you minted the key against
[NeverminedWidgets] initialize: invalid environmentenvironment is not a supported valueUse '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.