Embed Qirtaas for document creation

In this tutorial you add a notes feature to your website where an admin can create/edit/delete notes and any user can view them. The key architectural idea: Qirtaas is the notes backend. Documents are created, listed, and deleted from the frontend over the SDK’s embed-token channel, and each user’s embed identity scopes them to their own documents. Your backend needs exactly one change, a token endpoint, and zero new tables. What you’ll build

Backend: one token endpoint (the only backend change).
Frontend: a compose page with <QirtaasEditor>, a note list driven by listDocuments(), reopen-to-edit, and delete.

Frontend samples are React; the token endpoint is tabbed Node (Express) and Python (FastAPI). Prerequisites: a qrt_sk_… API key (see the Quickstart) and npm install @qirtaas/react.

1. Backend — add the token endpoint

The editor authenticates every request with a short-lived embed token, and only the secret key holder can mint one. Gate the endpoint with your app’s own auth and pass the authenticated user’s id as external_user_id: Qirtaas auto-provisions an identity per distinct id, and that identity is what scopes each user to their own documents (creation, listing, and deletion all happen within it).

// .env: QIRTAAS_API_KEY=qrt_sk_…
app.post("/api/qirtaas-token", requireAuth, async (req, res) => {
  const upstream = await fetch("https://api.qirtaas.io/v1/embed/tokens/", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.QIRTAAS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ external_user_id: String(req.user.id) }),
  });
  res.status(upstream.status).json(await upstream.json());
});

# env: QIRTAAS_API_KEY=qrt_sk_…
import os
import httpx
from fastapi import Depends

QIRTAAS_API_KEY = os.environ["QIRTAAS_API_KEY"]

@app.post("/api/qirtaas-token")
async def qirtaas_token(user=Depends(get_current_user)):
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            "https://api.qirtaas.io/v1/embed/tokens/",
            headers={"Authorization": f"Bearer {QIRTAAS_API_KEY}"},
            json={"external_user_id": str(user.id)},
            timeout=10,
        )
    resp.raise_for_status()
    return resp.json()  # {"token": "…", "expires_at": "…"}

Whoever can call this endpoint can edit that identity’s documents — always gate it with your own authentication and derive external_user_id from the session, never from the request body.

That’s the entire backend. Everything below is frontend.

2. Frontend

Create the client once and share it across your code. The same getToken powers the editor and the list/delete operations:

src/qirtaas.ts

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

export async function getToken(): Promise<string> {
  const res = await fetch("/api/qirtaas-token", { method: "POST" });
  if (!res.ok) throw new Error(`token fetch failed (${res.status})`);
  const { token } = await res.json();
  return token;
}

export const qirtaas = createQirtaasClient({ getToken });

3. Frontend — the compose page

Mount <QirtaasEditor> without a documentId: the SDK lazily creates the document on the first keystroke and hands you the new id via onDocumentCreated. The editor takes care of persisting any changes.

src/ComposeNote.tsx

import { QirtaasEditor } from "@qirtaas/react";
import { getToken } from "./qirtaas";

export function ComposeNote({
  onCreated,
}: {
  onCreated: (id: string) => void;
}) {
  return (
    // The editor fills its container — give it a bounded height.
    <div style={{ height: "70vh" }}>
      <QirtaasEditor
        getToken={getToken}
        locale="ar"
        theme="light"
        // e.g. update the route from /notes/new to /notes/<id>
        onDocumentCreated={onCreated}
        onSaveStateChange={(state) => console.log("save:", state)}
      />
    </div>
  );
}

Use onDocumentCreated for navigation concerns (swap /notes/new for /notes/<id> so a refresh reopens the same note) and onSaveStateChange for a saved/saving badge.

4. Frontend — Notes Dashboard

listDocuments() returns the identity’s documents:

src/NoteList.tsx

import { useEffect, useState } from "react";
import type { DocumentSummary } from "@qirtaas/react";
import { qirtaas } from "./qirtaas";

export function NoteList({ onOpen }: { onOpen: (id: string) => void }) {
  const [notes, setNotes] = useState<DocumentSummary[]>([]);

  useEffect(() => {
    qirtaas.listDocuments().then(setNotes);
  }, []);

  return (
    <ul>
      {notes.map((note) => (
        <li key={note.id} onClick={() => onOpen(note.id)}>
          {note.title || "Untitled"}
          <time>{new Date(note.updated_at).toLocaleDateString()}</time>
        </li>
      ))}
    </ul>
  );
}

Render the list with your own markup. Mount a Qirtaas embed only on the compose/read page, not per list item.

5. Frontend — reopen note

To continue an existing note, pass its id as documentId. The component mounts the editor once, so when the user switches notes, force a remount with a key:

src/EditNote.tsx

import { QirtaasEditor } from "@qirtaas/react";
import { getToken } from "./qirtaas";

export function EditNote({ docId }: { docId: string }) {
  return (
    <div style={{ height: "70vh" }}>
      <QirtaasEditor
        key={docId}
        documentId={docId}
        getToken={getToken}
        locale="ar"
        theme="light"
      />
    </div>
  );
}

Because the embed token is minted for the same external_user_id, the owner can reopen and edit any of their documents.

6. Frontend — delete a note

import { qirtaas } from "./qirtaas";

async function deleteNote(id: string) {
  await qirtaas.deleteDocument(id);
  setNotes(await qirtaas.listDocuments()); // refresh the list
}

That’s the whole lifecycle!

Where you are

Users can author, list, reopen, and delete rich documents, and your backend grew by one endpoint. Next:

Document reading

Show these notes read-only with the renderer.

Access control

Let other users read them, gated by your own ACL.

Get started

Tutorials

SDK

Auth

Self-hosting

AI

Embed Qirtaas for document creation

1. Backend — add the token endpoint

2. Frontend

3. Frontend — the compose page

4. Frontend — Notes Dashboard

5. Frontend — reopen note

6. Frontend — delete a note

Where you are

Document reading

Access control

​1. Backend — add the token endpoint

​2. Frontend

​3. Frontend — the compose page

​4. Frontend — Notes Dashboard

​5. Frontend — reopen note

​6. Frontend — delete a note

​Where you are

Document reading

Access control

1. Backend — add the token endpoint

2. Frontend

3. Frontend — the compose page

4. Frontend — Notes Dashboard

5. Frontend — reopen note

6. Frontend — delete a note

Where you are