Authentifizierung

Das Templatical SDK verwendet ein Backend-Proxy-Muster für die Authentifizierung. Ihre API-Zugangsdaten (Client ID und Client Secret) bleiben auf Ihrem Server — das SDK erhält nur kurzlebige Access Tokens.

Überblick

Der Authentifizierungsablauf umfasst drei Schritte:

1. API-Zugangsdaten erhalten — Erstellen Sie ein Projekt im Templatical-Dashboard und notieren Sie Ihre Client ID und Ihr Client Secret
2. Token-Endpunkt erstellen — Erstellen Sie einen Backend-Endpunkt, der Ihre Zugangsdaten gegen ein Access Token austauscht
3. SDK konfigurieren — Verweisen Sie die auth.url des SDK auf Ihren Token-Endpunkt

Das SDK ruft Ihren Token-Endpunkt automatisch bei der Initialisierung auf und erneuert das Token vor Ablauf (60 Sekunden vor Ablauf).

Token-Endpunkt

Ihr Backend benötigt einen Endpunkt, der:

1. Die Templatical-API mit Ihrer Client ID, Ihrem Client Secret und einer Mandanten-Kennung aufruft
2. Die Token-Antwort an den Browser zurückgibt

API-Anfrage

Senden Sie eine POST-Anfrage an den Templatical-Token-Endpunkt:

POST https://templatical.com/api/v1/auth/token
Content-Type: application/json

{
  "client_id": "ihre-client-id",
  "client_secret": "ihr-client-secret",
  "tenant": "mandanten-kennung"
}

Feld	Typ	Beschreibung
client_id	string	Die Client ID Ihres Projekts
client_secret	string	Das Client Secret Ihres Projekts
tenant	string	Eine eindeutige Kennung für den Mandanten (Benutzer/Organisation) in Ihrem System

Das Feld tenant isoliert Daten zwischen verschiedenen Benutzern oder Organisationen in Ihrer Anwendung. Jeder Mandant erhält eigene Templates, Medien-Assets und Einstellungen — sie können nicht auf die Daten anderer Mandanten zugreifen. Verwenden Sie einen beliebigen stabilen, eindeutigen String aus Ihrem System als Mandanten-Kennung, z. B. eine Organisations-ID, einen Team-Slug oder eine Benutzer-ID. Wenn Ihre Anwendung beispielsweise Workspaces hat, könnten Sie die Workspace-ID verwenden, damit alle Mitglieder desselben Workspace die gleichen Templates teilen. Wenn eine noch nicht existierende Mandanten-Kennung übergeben wird, erstellt Templatical automatisch einen neuen Mandanten dafür.

API-Antwort

Der Token-Endpunkt gibt zurück:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": 1709251200,
  "project_id": "proj_abc123",
  "tenant": "acme-corp"
}

Feld	Typ	Beschreibung
token	string	Bearer Access Token für API-Anfragen
expires_at	number	Unix-Zeitstempel (Sekunden) für den Ablauf des Tokens. Tokens sind 10 Minuten gültig
project_id	string	Ihre Projekt-Kennung
tenant	string	Der aufgelöste Mandanten für diese Sitzung

Ihr Backend sollte diese gesamte Antwort unverändert an den Browser weiterleiten.

Backend-Beispiele

app.post('https://your-app.com/api/token', async (req, res) => {
  const response = await fetch('https://templatical.com/api/v1/auth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: process.env.TEMPLATICAL_CLIENT_ID,
      client_secret: process.env.TEMPLATICAL_CLIENT_SECRET,
      tenant: req.user.organizationId,
    }),
  });

  const tokenData = await response.json();
  res.json(tokenData);
});

SDK-Konfiguration

Sobald Ihr Token-Endpunkt bereit ist, konfigurieren Sie das SDK:

import { init } from '@templatical/embedded';

const editor = await init({
  container: '#email-editor',
  auth: {
    url: 'https://your-app.com/api/token',
  },
});

Benutzerdefinierte Anfrage-Optionen

Wenn Ihr Token-Endpunkt bestimmte HTTP-Methoden, Headers oder einen Request-Body erfordert, verwenden Sie die Eigenschaft auth.requestOptions:

const editor = await init({
  container: '#email-editor',
  auth: {
    url: 'https://your-app.com/api/token',
    requestOptions: {
      method: 'POST',              // 'GET' oder 'POST' (Standard: 'POST')
      headers: {
        'X-Custom-Header': 'value',
      },
      body: {
        workspace_id: 'ws_123',    // Zusätzliche Daten zum Senden
      },
    },
  },
});

Option	Typ	Standard	Beschreibung
method	'GET' | 'POST'	'POST'	HTTP-Methode für die Token-Anfrage
headers	Record<string, string>	{}	Zusätzliche Headers
body	Record<string, unknown>	—	JSON-Body zum Senden (nur POST)

Das SDK fügt automatisch Accept: application/json und Content-Type: application/json Headers hinzu. Es sendet auch Cookies mit der Anfrage (credentials: 'include'), sodass sitzungsbasierte Authentifizierung sofort funktioniert.

Fehlerbehandlung

Behandeln Sie Authentifizierungsfehler mit dem onError-Callback in der Hauptkonfiguration:

const editor = await init({
  container: '#email-editor',
  auth: {
    url: 'https://your-app.com/api/token',
  },
  onError: (error) => {
    if (error.statusCode === 401) {
      // Token-Endpunkt gab Unauthorized zurück — zur Anmeldung weiterleiten
      window.location.href = '/login';
    } else {
      console.error('Editor-Fehler:', error.message);
    }
  },
});

Das error-Objekt ist eine Instanz von SdkError mit diesen Eigenschaften:

Eigenschaft	Typ	Beschreibung
message	string	Lesbare Fehlermeldung
statusCode	number | undefined	HTTP-Statuscode (wenn von einer API-Antwort)
isNotFound	boolean	true wenn statusCode 404 ist
isUnauthorized	boolean	true wenn statusCode 401 ist
isServerError	boolean	true wenn statusCode 500+ ist

Token-Erneuerung

Das SDK verwaltet den Token-Lebenszyklus automatisch. Jedes Token ist 10 Minuten gültig:

• Bei der Initialisierung wird ein Token von Ihrem Endpunkt abgerufen
• Vor Ablauf des Tokens (60 Sekunden vorher) wird ein neues abgerufen
• Wenn eine API-Anfrage 401 zurückgibt, wird das Token erneuert und die Anfrage einmal wiederholt
• Gleichzeitige Erneuerungsanfragen werden dedupliziert — nur ein Netzwerkaufruf wird durchgeführt

Sie müssen keine Token-Erneuerungslogik in Ihrer Anwendung implementieren.

Sicherheits-Best-Practices

• Geben Sie Ihr Client Secret niemals im Frontend-Code preis. Tauschen Sie Zugangsdaten immer auf Ihrem Backend aus.
• Verwenden Sie HTTPS für Ihren Token-Endpunkt und alle Kommunikation.
• Mandanten korrekt zuordnen. Stellen Sie sicher, dass Ihr Token-Endpunkt die richtige Mandanten-Kennung für jede Anfrage übergibt. Templates, Medien und Einstellungen sind pro Mandant isoliert — die falsche Kennung gewährt Zugriff auf die falschen Daten.

Nächste Schritte

• Konfiguration — Alle Konfigurationsoptionen, Callbacks und Instanzmethoden