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 API

4. If valid, you serve the premium content

---

Setup: API key

Before you can verify sessions, create an API key in the dashboard: go to 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, the payload includes a sessionId. Pass it to your backend when fetching premium content.

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 API to confirm the session is valid before serving content.

Endpoint:

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

Base URLs:

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

Header: X-ACCESS-TOKEN: <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) {
    return res.status(401).json({ error: 'No session ID' });
  }

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

  if (tiunResponse.status === 200) {
    res.json({ content: 'Your premium article content here' });
  } else if (tiunResponse.status === 404) {
    res.status(403).json({ error: 'Session expired or invalid' });
  } else {
    res.status(502).json({ error: 'Verification failed' });
  }
});

---

Full round-trip

Frontend — capture the session ID and fetch content:

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

tiun.init({
  snippetId: 'YOUR_SNIPPET_ID',
  language: 'en', // set to your site's language
});

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) {
    return res.status(401).json({ error: 'No session ID' });
  }

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

  if (upstream.status === 200) {
    res.json({ content: 'Premium article content' });
  } else {
    res.status(403).json({ error: 'Access denied' });
  }
});

---

Use the sandbox base URL while developing. Switch to the production URL when you go live.

For a conceptual overview of session verification, see Verifying Access in the Docs.