Quickstart

This guide mounts a working editor in a React app against the managed cloud. If you plan to run your own backend, everything below is identical except the apiUrl — see Self-hosting.

Using Vue or vanilla JS instead? The flow is exactly the same — install @qirtaas/vue or @qirtaas/core and swap the component code in steps 4–5 for their equivalents.

1. Get an API key

Qirtaas cloud keys are provisioned per organization. Fill out the key request form and you’ll receive:

a secret API key (qrt_sk_…) — used by your backend only to mint embed tokens. Never ship it to the browser.
a signing secret — only needed for cross-user renderer reads, see Authentication.

Self-hosting instead? Skip this step and issue your own tokens — see Self-hosting.

2. Install

npm install @qirtaas/react

The package wraps the core SDK in two components — <QirtaasEditor> and <QirtaasRenderer> — with only React as a peer dependency.

3. Add a token endpoint to your backend

This step is required and happens outside the SDK: the editor authenticates with a short-lived embed token, and only your backend — holding the qrt_sk_… secret — can mint one. Add an endpoint that:

Authenticates the request with your app’s own session/auth.
Exchanges the secret key for an embed token by calling POST https://api.qirtaas.io/v1/embed/tokens/.
Returns the token to the browser.

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",
    },
    // Any stable id for this end user in YOUR system. Qirtaas
    // auto-provisions an identity under your org for each id.
    body: JSON.stringify({ external_user_id: String(req.user.id) }),
  });
  res.status(upstream.status).json(await upstream.json());
});

import os
import httpx
from fastapi import FastAPI, Depends

app = FastAPI()
QIRTAAS_API_KEY = os.environ["QIRTAAS_API_KEY"]  # qrt_sk_…

@app.post("/api/qirtaas-token")
async def qirtaas_token(user=Depends(get_current_user)):  # your auth
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            "https://api.qirtaas.io/v1/embed/tokens/",
            headers={"Authorization": f"Bearer {QIRTAAS_API_KEY}"},
            # Any stable id for this end user in YOUR system. Qirtaas
            # auto-provisions an identity under your org for each id.
            json={"external_user_id": str(user.id)},
            timeout=10,
        )
    resp.raise_for_status()
    return resp.json()  # {"token": "…", "expires_at": "…"}

import os
import requests
from django.contrib.auth.decorators import login_required
from django.http import JsonResponse
from django.views.decorators.http import require_POST

@login_required
@require_POST
def qirtaas_token(request):
    resp = requests.post(
        "https://api.qirtaas.io/v1/embed/tokens/",
        headers={"Authorization": f"Bearer {os.environ['QIRTAAS_API_KEY']}"},
        json={"external_user_id": str(request.user.id)},
        timeout=10,
    )
    resp.raise_for_status()
    return JsonResponse(resp.json())  # {"token": "…", "expires_at": "…"}

Never put your qrt_sk_… secret key in the browser. The frontend only ever sees the short-lived embed token (1 hour TTL); the SDK calls your endpoint again before expiry and on 401. Full endpoint reference: Authentication.

4. Mount the editor

Wire the component’s getToken to the endpoint from step 3.

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

async function getToken() {
  const res = await fetch("/api/qirtaas-token", { method: "POST" });
  const { token } = await res.json();
  return token;
}

export function Compose() {
  return (
    // The editor fills its container — give it a bounded height.
    <div style={{ height: "70vh" }}>
      <QirtaasEditor
        getToken={getToken}
        locale="ar"
        theme="light"
        // Omit documentId to lazily create a document on first edit.
        onDocumentCreated={(id) => console.log("new document:", id)}
        onChange={(json) => console.log("content changed", json)}
      />
    </div>
  );
}

That’s it — the editor autosaves as the user types. See React for all props, the ref handle, and remount rules, and Editor for autosave control.

5. Display a saved document

Use the read-only renderer to show a document without editing:

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

<QirtaasRenderer
  documentId="b1f2…"
  shareToken="…" // public read; or use getToken / getSignature
  theme="light"
/>

See Renderer for the three auth modes (share token, embed token, HMAC signature).

Next steps

The tutorials walk a real feature end to end — backend and frontend together:

Document creation

Create, list, edit, and delete documents with one backend endpoint.

Document reading

Render saved documents for their authors and the public.

Access control

Gate cross-user reads behind your own ACL with signatures.

Get started

Tutorials

SDK

Auth

Self-hosting

AI

1. Get an API key

2. Install

3. Add a token endpoint to your backend

4. Mount the editor

5. Display a saved document

Next steps

Document creation

Document reading

Access control

​1. Get an API key

​2. Install

​3. Add a token endpoint to your backend

​4. Mount the editor

​5. Display a saved document

​Next steps

Document creation

Document reading

Access control

1. Get an API key

2. Install

3. Add a token endpoint to your backend

4. Mount the editor

5. Display a saved document

Next steps