Verify authentication server-side

Client-side checks (isAuthenticated, userChange) are enough for UI gating, but your backend should not trust the browser alone. This guide walks you through verifying a tiun user's identity on your server before serving protected data.

---

How it works

1. Your frontend asks tiun for a signed verification token.

2. It sends that token to your backend on protected requests.

3. Your backend exchanges the token with the tiun UserVerification API for the user object.

4. If the user object reports isAuthenticated: true, you serve the protected data.

The token is a signed JWT, valid for 5 minutes. The verified user object includes isAuthenticated plus a userInfo payload (userId, email, productAccess) — see User object in Reference for the full shape.

---

Setup: API key

Before you can verify users on your server, 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. Get the verification token

Call getUserVerificationToken() on the frontend. It returns a token if the user is authenticated, or null if they're not. Attach it to your API request — most commonly as a Bearer token in the Authorization header.

async function fetchProtectedData() {
  const token = await tiun.getUserVerificationToken();

  if (!token) {
    return null;
  }

  const response = await fetch('/api/protected', {
    headers: {
      Authorization: `Bearer ${token}`,
    },
  });

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

---

2. Verify the token on your server

Call the tiun UserVerification API to exchange the token for the user object.

Endpoint:

POST /live_api/s2s/v1/users/verification

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>

Body: { "userVerificationToken": "<token>" }

Response codes:

Status	Meaning
200	User object returned — read the body
401	API key is invalid

A 200 response carries the user object:

{
  "isAuthenticated": true,
  "userInfo": {
    "userId": "u-...",
    "email": "[e-mail]",
    "productAccess": ["p-live-..."]
  }
}

---

3. Check isAuthenticated

Once you have the user object, gate the response on isAuthenticated. If it's false, treat the request as unauthenticated — the API key was accepted but the underlying user session is no longer active.

For subscription-specific gating on top of identity, see server-side subscription verification — same endpoint, plus a productAccess check.

---

Full round-trip

Frontend — request protected data after auth state is known:

tiun.on('userChange', async (data) => {
  if (!data.isAuthenticated) {
    showPublicContent();
    return;
  }

  const result = await fetchProtectedData();

  if (result) {
    showProtectedContent(result);
  }
});

async function fetchProtectedData() {
  const token = await tiun.getUserVerificationToken();

  if (!token) return null;

  const res = await fetch('/api/protected', {
    headers: { Authorization: `Bearer ${token}` },
  });

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

Backend — exchange the token for the user object 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/protected', async (req, res) => {
  const auth = req.headers.authorization;
  const token = auth?.startsWith('Bearer ') ? auth.slice(7) : null;

  if (!token) {
    // missing token → reject as unauthenticated
    return;
  }

  const tiunResponse = await fetch(
    `${BASE_URL}/live_api/s2s/v1/users/verification`,
    {
      method: 'POST',
      headers: {
        'X-TIUN-API-KEY': API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ userVerificationToken: token }),
    },
  );

  if (tiunResponse.status !== 200) {
    // API key invalid or upstream error → fail closed
    return;
  }

  const user = await tiunResponse.json();

  if (!user.isAuthenticated) {
    // token was exchanged but the user has no active session → reject
    return;
  }

  // user authenticated → serve the protected content
  // user.userInfo carries userId, email, productAccess
});

---

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.