Sessions and access tokens

A session in ArcenPay is a short-lived identity token that your backend mints and passes to the frontend. It tells ArcenPay which company and user are currently active, and it controls what ArcenEmbed is allowed to show. Understanding when to use server-minted tokens versus the standard publishable key flow lets you choose the right security model for your integration.

Two identity paths

ArcenPay supports two ways to establish the customer’s identity in the browser. Publishable key + identify() — the standard path. You initialise ArcenPayProvider with your publishable key and call identify() from the React SDK once the customer’s wallet is resolved. This is the recommended path for most integrations. Server-minted access token — you call client.identify() on your backend to mint a short-lived token, then pass it to ArcenEmbed via the accessToken prop. Use this path when you need stronger server-side control over which billing surface a specific customer can access, or when you are integrating into a context where the publishable key + identify() flow is not suitable.

The publishable key + identify() path is the default and is sufficient for most apps. You only need to mint server-side tokens when you require explicit backend control over the embed session.

Minting a session token on the server

Use client.identify() from the Node SDK to create a session. Pass the company and user identifiers along with an optional expiresIn value in seconds.

import { ArcenClient } from "@arcenpay/node";

const client = new ArcenClient({
  apiKey: process.env.ARCENPAY_API_KEY!,
});

const session = await client.identify({
  company: { id: "company_123", wallet: "0xabc..." },
  user: { id: "user_123", wallet: "0xabc..." },
  expiresIn: 3600,
});

The returned session object contains the access token. Return this token from your API route and pass it to the frontend.

Passing the token to ArcenEmbed

Once you have the token on the client, pass it directly to ArcenEmbed via the accessToken prop. You can also specify a componentId here if you are not relying on the value set in ArcenPayProvider.

import { ArcenEmbed } from "@arcenpay/react";

export function BillingPage({ token }: { token: string }) {
  return <ArcenEmbed accessToken={token} componentId="cmp_123" />;
}

Fetch a fresh token from your backend API route on the billing page load, rather than storing it in long-lived client state. This keeps the token’s lifetime short and tied to the user’s current session.

Token expiry and refresh

Tokens expire after the duration set in expiresIn (in seconds). Once a token expires, ArcenEmbed will no longer be able to authenticate the session. To handle this:

Set expiresIn to a value that covers the expected time the customer will spend on the billing surface (for example, 3600 for one hour).
If your application supports long-lived billing pages, implement a refresh mechanism that fetches a new token from your backend and updates the accessToken prop before the current one expires.

Do not expose your ARCENPAY_API_KEY in the browser. The client.identify() call must happen server-side. Return only the resulting access token to the client.

When to use each path

Scenario	Recommended path
Standard SaaS app with wallet-connected users	Publishable key + `identify()`
Server-rendered page where you control the embed surface per request	Server-minted `accessToken`
High-security context where client should not hold a publishable key	Server-minted `accessToken`
Embedding billing inside a third-party iframe or widget	Server-minted `accessToken`

Next steps

Quickstart — see both identity paths in the context of a full integration.
Feature entitlements and flags — control access to features after the session is established.

Get started

Core concepts

Guides

Integrations

Sessions and access tokens

Two identity paths

Minting a session token on the server

Passing the token to ArcenEmbed

Token expiry and refresh

When to use each path

Next steps

​Two identity paths

​Minting a session token on the server

​Passing the token to ArcenEmbed

​Token expiry and refresh

​When to use each path

​Next steps

Two identity paths

Minting a session token on the server

Passing the token to ArcenEmbed

Token expiry and refresh

When to use each path

Next steps