Verify sessions server-side

For time-based billing, access is controlled through paywall events on the client. But if your backend serves premium content (articles, streams, API data), you need to verify the session on the server before delivering it. This guide walks you through that flow.

---

How it works

1. The paywallHide event includes a sessionId when the user has access.

2. Your frontend sends that session ID to your backend.

3. Your backend validates it against the tiun Session API.

4. If valid, you serve the premium content.

For the sessionId concept itself and its lifecycle, see Sessions in Reference.

---

Setup: API key

Before you can verify sessions, create an API key in the dashboard: open APIs in the sidebar and click Create new key. Store it securely in your backend environment variables.

---

1. Capture the session ID

When paywallHide fires, its payload includes a sessionId. Pass it to your backend on the protected request.

tiun.on('paywallHide', async (data) => {
  const content = await fetchPremiumContent(data.sessionId);

  if (content) {
    renderContent(content);
  }
});

async function fetchPremiumContent(sessionId) {
  const response = await fetch('/api/premium-content', {
    headers: {
      'X-Session-Id': sessionId,
    },
  });

  if (!response.ok) return null;
  return response.json();
}

---

2. Validate the session on your server

Call the tiun Session API to confirm the session is valid before serving content.

Endpoint:

PATCH /live_api/s2s/v1/sessions/{sessionId}/status

Base URLs:

Environment	URL
Live	https://api.tiun.live
Sandbox	https://api-sandbox.tiun.live

Use the base URL and API key from the same environment as your frontend (sandbox: true in the SDK → sandbox URL and sandbox key). API keys are not shared between live and sandbox.

Header: X-TIUN-API-KEY: <your-api-key>

Response codes:

Status	Meaning
200	Session is valid — serve the content
404	Session is invalid, expired, or user has no funds
401	API key is incorrect

---

3. Backend implementation

import express from 'express';

const app = express();

const BASE_URL = process.env.TIUN_API_BASE || 'https://api-sandbox.tiun.live';
const API_KEY = process.env.TIUN_API_KEY;

app.get('/api/premium-content', async (req, res) => {
  const sessionId = req.headers['x-session-id'];

  if (!sessionId) {
    // missing session id → reject as no access
    return;
  }

  const tiunResponse = await fetch(
    `${BASE_URL}/live_api/s2s/v1/sessions/${sessionId}/status`,
    {
      method: 'PATCH',
      headers: { 'X-TIUN-API-KEY': API_KEY },
    },
  );

  if (tiunResponse.status === 200) {
    // session valid → serve the premium content
  } else if (tiunResponse.status === 404) {
    // session invalid, expired, or user out of funds → deny
  } else {
    // unexpected error from tiun → fail closed
  }
});

---

Full round-trip

Frontend — capture the session ID and fetch content:

import { tiun } from '@tiun/sdk';

tiun.init({
  snippetId: 'YOUR_SNIPPET_ID',
  language: 'en',
});

tiun.on('paywallHide', async (data) => {
  const response = await fetch('/api/premium-content', {
    headers: { 'X-Session-Id': data.sessionId },
  });

  if (response.ok) {
    const content = await response.json();
    renderContent(content);
  }
});

tiun.on('paywallShow', () => {
  showPaywall();
});

Backend — validate and serve:

import express from 'express';

const app = express();

const BASE_URL = process.env.TIUN_API_BASE || 'https://api-sandbox.tiun.live';
const API_KEY = process.env.TIUN_API_KEY;

app.get('/api/premium-content', async (req, res) => {
  const sessionId = req.headers['x-session-id'];

  if (!sessionId) {
    // missing session id → reject as no access
    return;
  }

  const upstream = await fetch(
    `${BASE_URL}/live_api/s2s/v1/sessions/${sessionId}/status`,
    {
      method: 'PATCH',
      headers: { 'X-TIUN-API-KEY': API_KEY },
    },
  );

  if (upstream.status === 200) {
    // session valid → serve the premium content
  } else {
    // session invalid or upstream error → deny
  }
});

---

Live and sandbox are independent environments — each has its own API base URL and API keys. Use sandbox credentials while your app runs with sandbox: true; switch URL and key together when you ship live traffic. See Sandbox.