Customer-Facing Activity Feed

Multi-tenant SaaS applications often need to show customers their own activity history — who on their team did what and when. Immutable’s viewer tokens let you securely expose a read-only, tenant-scoped view of the audit log without giving customers access to your API key or other tenants’ data.

How It Works

Your backend creates a viewer token scoped to a specific tenant_id
The token is passed to your frontend
Your frontend either embeds the Immutable viewer iframe or queries the public events endpoint directly
The token expires after the configured TTL

Creating Viewer Tokens

Backend: Generate a Token

JavaScript
Python
Laravel
cURL

import { ImmutableClient } from "getimmutable";

const client = new ImmutableClient({
  apiKey: "imk_sk_a1b2c3d4e5f6g7h8i9j0",
  baseUrl: "https://getimmutable.dev",
});

// Scoped to the customer's organization
const token = await client.createViewerToken({
  tenantId: "org_acme_corp",
  ttl: 3600,
});

// Send token.viewer_token to your frontend
console.log(token.viewer_token);
// "vt_eyJhbGciOiJIUzI1NiIs..."

from getimmutable import ImmutableClient

client = ImmutableClient(
    api_key="imk_sk_a1b2c3d4e5f6g7h8i9j0",
    base_url="https://getimmutable.dev"
)

token = client.create_viewer_token(tenant_id="org_acme_corp", ttl=3600)

# Send token["viewer_token"] to your frontend
print(token["viewer_token"])

use GetImmutable\Laravel\Facades\AuditLog;

// In your controller, generate a token for the authenticated user's org
$token = AuditLog::createViewerToken([
    'tenant_id' => $request->user()->organization_id,
    'ttl' => 3600,
]);

return response()->json(['viewer_token' => $token['viewer_token']]);

curl -X POST https://getimmutable.dev/api/v1/viewer-tokens \
  -H "Authorization: Bearer imk_sk_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "org_acme_corp", "ttl": 3600}'

Scoping by Actor

You can also scope a viewer token to a specific actor, so a user only sees their own activity:

JavaScript
Python
cURL

const token = await client.createViewerToken({
  tenantId: "org_acme_corp",
  actorId: "user_5a3c8f",
  ttl: 3600,
});

token = client.create_viewer_token(
    tenant_id="org_acme_corp",
    actor_id="user_5a3c8f",
    ttl=3600
)

curl -X POST https://getimmutable.dev/api/v1/viewer-tokens \
  -H "Authorization: Bearer imk_sk_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "org_acme_corp",
    "actor_id": "user_5a3c8f",
    "ttl": 3600
  }'

Viewer tokens are read-only and cannot be used to ingest events. They only grant access to events matching the scoped tenant_id (and optionally actor_id).

Embedding the Viewer

Option 1: Iframe Embed

The simplest integration — embed the Immutable viewer directly in your app:

<iframe
  src="https://getimmutable.dev/viewer?token=vt_eyJhbGciOiJIUzI1NiIs..."
  width="100%"
  height="600"
  frameborder="0"
  style="border-radius: 8px; border: 1px solid #e5e7eb;"
></iframe>

Option 2: React Component

Build a custom activity feed by querying the public events endpoint with the viewer token:

import { useState, useEffect } from "react";

function ActivityFeed({ viewerToken }) {
  const [events, setEvents] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function fetchEvents() {
      const response = await fetch(
        "https://getimmutable.dev/api/v1/events?limit=50",
        {
          headers: {
            Authorization: `Bearer ${viewerToken}`,
          },
        }
      );
      const data = await response.json();
      setEvents(data.data);
      setLoading(false);
    }
    fetchEvents();
  }, [viewerToken]);

  if (loading) {
    return (
      <div className="animate-pulse space-y-3">
        {[...Array(5)].map((_, i) => (
          <div key={i} className="h-12 bg-gray-100 rounded" />
        ))}
      </div>
    );
  }

  return (
    <div className="divide-y divide-gray-100">
      {events.map((event) => (
        <div key={event.id} className="py-3 flex items-start gap-3">
          <div className="w-8 h-8 rounded-full bg-blue-100 flex items-center justify-center text-sm font-medium text-blue-700">
            {event.actor_name?.charAt(0) || "?"}
          </div>
          <div className="flex-1 min-w-0">
            <p className="text-sm text-gray-900">
              <span className="font-medium">{event.actor_name}</span>{" "}
              {formatAction(event.action)}{" "}
              <span className="font-medium">{event.resource_name}</span>
            </p>
            <p className="text-xs text-gray-500 mt-0.5">
              {new Date(event.occurred_at).toLocaleString()}
            </p>
          </div>
        </div>
      ))}
    </div>
  );
}

function formatAction(action) {
  return action.replace(/\./g, " ").replace(/_/g, " ");
}

When building a custom activity feed, implement cursor-based pagination using the cursor parameter from the API response. This ensures you can load older events without missing any.

TTL Management

Choose a TTL that matches your use case:

Scenario	Recommended TTL	Reason
Dashboard page view	3600 (1 hour)	Matches typical session length
Embedded widget	900 (15 minutes)	Short-lived, refresh on page load
Customer portal	28800 (8 hours)	Full work day access
Single report view	300 (5 minutes)	Minimal exposure

Refreshing Tokens

Create a backend endpoint that generates fresh tokens on demand:

JavaScript (Express)
Python (Flask)
Laravel

app.get("/api/activity-token", authenticate, async (req, res) => {
  const token = await client.createViewerToken({
    tenantId: req.user.organizationId,
    ttl: 3600,
  });
  res.json({ token: token.viewer_token, expires_in: 3600 });
});

@app.route("/api/activity-token")
@login_required
def activity_token():
    token = client.create_viewer_token(
        tenant_id=current_user.organization_id,
        ttl=3600
    )
    return jsonify({"token": token["viewer_token"], "expires_in": 3600})

// routes/web.php
Route::get('/api/activity-token', function (Request $request) {
    $token = AuditLog::createViewerToken([
        'tenant_id' => $request->user()->organization_id,
        'ttl' => 3600,
    ]);

    return response()->json([
        'token' => $token['viewer_token'],
        'expires_in' => 3600,
    ]);
})->middleware('auth');

On the frontend, refresh the token before it expires:

function useViewerToken() {
  const [token, setToken] = useState(null);

  useEffect(() => {
    async function refresh() {
      const res = await fetch("/api/activity-token");
      const data = await res.json();
      setToken(data.token);

      // Refresh 60 seconds before expiry
      const refreshMs = (data.expires_in - 60) * 1000;
      setTimeout(refresh, refreshMs);
    }
    refresh();
  }, []);

  return token;
}

Querying Events with a Viewer Token

Viewer tokens work with the same events API, but responses are automatically filtered to the token’s scope:

JavaScript
cURL

// Using the viewer token directly (no SDK needed on the frontend)
const response = await fetch(
  "https://getimmutable.dev/api/v1/events?action=project.created&limit=10",
  {
    headers: { Authorization: "Bearer vt_eyJhbGciOiJIUzI1NiIs..." },
  }
);
const events = await response.json();

curl "https://getimmutable.dev/api/v1/events?action=project.created&limit=10" \
  -H "Authorization: Bearer vt_eyJhbGciOiJIUzI1NiIs..."

Even if a query doesn’t include tenant_id as a filter, the viewer token enforces it. A viewer token scoped to org_acme_corp can never see events from other tenants.

What’s Next

Embeddable Viewer

Full guide to the Immutable viewer widget.

Events API

API reference for querying events.

Viewer Token API

API reference for creating viewer tokens.

SaaS Activity Tracking

End-to-end example of tracking user activity in a SaaS app.

Industry

Patterns

Customer-Facing Activity Feed

How It Works

Creating Viewer Tokens

Backend: Generate a Token

Scoping by Actor

Embedding the Viewer

Option 1: Iframe Embed

Option 2: React Component

TTL Management

Refreshing Tokens

Querying Events with a Viewer Token

What’s Next

Embeddable Viewer

Events API

Viewer Token API

SaaS Activity Tracking

​How It Works

​Creating Viewer Tokens

​Backend: Generate a Token

​Scoping by Actor

​Embedding the Viewer

​Option 1: Iframe Embed

​Option 2: React Component

​TTL Management

​Refreshing Tokens

​Querying Events with a Viewer Token

​What’s Next

Embeddable Viewer

Events API

Viewer Token API

SaaS Activity Tracking

How It Works

Creating Viewer Tokens

Backend: Generate a Token

Scoping by Actor

Embedding the Viewer

Option 1: Iframe Embed

Option 2: React Component

TTL Management

Refreshing Tokens

Querying Events with a Viewer Token

What’s Next