Session lifecycle

How long a session lasts

Stage	Lifetime
Session code from `POST /auth`	2 minutes, one use
Session, once the widget redeems the code	1 hour from your `POST /auth` call

The session doesn’t extend with activity. When it ends, the widget stops operating and asks you for a new code.

Events

The widget emits DOM events on the <ripio-crypto-widget> element. They bubble and cross the Shadow DOM boundary, so you can listen on the element itself or on any ancestor.

Event	`detail`	When
`ripio-session-expired`	`{ reason: "session_lost" }`	The session ended: the code was invalid, expired or already used, the hour ran out, or Ripio revoked it. Fired as soon as it happens.
`ripio-session-expired`	`{ reason: "user_retry" }`	The user pressed the button on the “session ended” screen.
`ripio-handoff`	`{ reason: "not_operable" }`	The session is valid, but the user can’t operate yet — for example, their identity verification isn’t complete. Send them to the right place in your app.

In a WebView there is no page of yours to listen on, so the widget also posts {"type": "ripio-session-expired"} to your app’s native bridge — see Mobile / WebView integration.

Renewing a session

Request a new code from your server and pass it to the widget. It starts the new session and returns the user to the home screen, without reloading your page:

const widget = document.querySelector("ripio-crypto-widget");

widget.addEventListener("ripio-session-expired", async () => {
  const { session_code } = await fetch("/your-backend/ripio-session").then((r) => r.json());
  widget.renew(session_code);
});

Setting the code property again has the same effect as calling renew. In a WebView, you can also load the same page with a new #_co= fragment.

Reloading the page doesn’t renew anything. The code in the URL was already used, so a reload lands on the same “session ended” screen. The widget doesn’t reload your page on its own either.

A new code can belong to a different external_ref — for example, if a different user logs into your app on the same device. The widget starts from a clean state for every renewal.

Overview

Widget

API Reference

How long a session lasts

Events

Renewing a session

​How long a session lasts

​Events

​Renewing a session

How long a session lasts

Events

Renewing a session