Access-control content with signatures

The first two tutorials cover authors reading their own documents (embed token) and fully public documents (share token). This one covers the case in between: another signed-in user reads a document, and your app decides whether they may. (ex: a student viewing a teacher’s lesson). Embed tokens can’t express this: they are scoped to one identity’s own documents, and minting the author’s token for a reader would let them edit. Instead, the renderer accepts a per-document, expiring HMAC signature that your backend computes after running whatever access check you like:

signature = hex(HMAC_SHA256(signing_secret, "<document_id>|<exp>"))

Qirtaas holds the same signing secret and recomputes the HMAC to verify. The signature is your backend’s short-lived approval stamp: “this reader may read this document until exp”. The ACL itself never leaves your database. Example scenario: a course platform. Teachers author lesson documents (the creation flow, unchanged); enrolled students read them.

1. Backend — the data model

We will track lessons (which contain Qirtaas documents) and student enrollments.

lessons(id, course_id, title, qirtaas_doc_id, …)
enrolments(user_id, course_id, …)

2. Backend — gated signature endpoint

We will add a signing helper function …

// env: QIRTAAS_SIGNING_SECRET=…
import { createHmac } from "node:crypto";

const SIGNING_SECRET = process.env.QIRTAAS_SIGNING_SECRET!;

export function signRead(docId: string, ttlSeconds = 3600) {
  const exp = Math.floor(Date.now() / 1000) + ttlSeconds;
  const signature = createHmac("sha256", SIGNING_SECRET)
    .update(`${docId}|${exp}`)
    .digest("hex");
  return { signature, exp };
}

# env: QIRTAAS_SIGNING_SECRET=…
import hashlib, hmac, os, time

SIGNING_SECRET = os.environ["QIRTAAS_SIGNING_SECRET"]

def sign_read(doc_id: str, ttl: int = 3600) -> dict:
    exp = int(time.time()) + ttl
    sig = hmac.new(
        SIGNING_SECRET.encode(),
        f"{doc_id}|{exp}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return {"signature": sig, "exp": exp}

… then we will expose a function in the backend that signs documents after performing ACL checks.

import { signRead } from "./qirtaasSigning";

app.get("/api/lessons/:id/signature", requireAuth, async (req, res) => {
const lesson = await db.lessons.findUnique({
where: { id: Number(req.params.id) },
});
if (!lesson) return res.status(404).json({ error: "Lesson not found" });

// The ACL check — entirely yours. Here: must be enrolled in the course.
const enrolled = await db.enrolments.findFirst({
where: { user_id: req.user.id, course_id: lesson.course_id },
});
if (!enrolled) return res.status(403).json({ error: "not_enrolled" });

res.json(signRead(lesson.qirtaas_doc_id)); // { signature, exp }
});

from .qirtaas_signing import sign_read

@app.get("/api/lessons/{lesson_id}/signature")
async def lesson_signature(lesson_id: int, user=Depends(get_current_user)):
    lesson = await db.lessons.find_first(id=lesson_id)
    if lesson is None:
        raise HTTPException(404, "Lesson not found")

    # The ACL check — entirely yours. Here: must be enrolled in the course.
    enrolled = await db.enrolments.find_first(
        user_id=user.id, course_id=lesson.course_id
    )
    if enrolled is None:
        raise HTTPException(403, "not_enrolled")

    return sign_read(lesson.qirtaas_doc_id)  # { signature, exp }

4. Frontend — render with `getSignature`

Give the renderer getSignature instead of getToken. The renderer sends the pair as ?sig=&exp= query parameters on its read:

src/LessonView.tsx

import { QirtaasRenderer } from "@qirtaas/react";

export function LessonView({ lesson }: { lesson: Lesson }) {
  async function getSignature() {
    const res = await fetch(`/api/lessons/${lesson.id}/signature`);
    if (!res.ok) throw new Error(`signature fetch failed (${res.status})`);
    return res.json(); // { signature, exp }
  }

  return (
    <QirtaasRenderer
      key={lesson.qirtaas_doc_id}
      documentId={lesson.qirtaas_doc_id}
      getSignature={getSignature}
      locale="ar"
      theme="light"
      onError={(code) => console.error("render failed:", code)}
    />
  );
}

Security checklist

The signing secret lives in backend env/config only.
Check access before signing, and sign only the specific document the check covered. Never sign ids taken from the request unchecked.
Signatures grant read-only access to one document. There is no wildcard signature, so a leaked one is contained to a single document until its exp.

Full reference: Authentication — signatures.

Get started

Tutorials

SDK

Auth

Self-hosting

AI

Access-control content with signatures

1. Backend — the data model

2. Backend — gated signature endpoint

4. Frontend — render with `getSignature`

Security checklist

​1. Backend — the data model

​2. Backend — gated signature endpoint

​4. Frontend — render with getSignature

​Security checklist

1. Backend — the data model

2. Backend — gated signature endpoint

4. Frontend — render with `getSignature`

Security checklist