API-Schlüssel

AACsearch verwendet drei Arten von API-Schlüsseln, jede mit einem eigenen Präfix und Berechtigungsbereich. Alle Schlüssel werden als bcrypt-Hashes gespeichert – der Klartext wird einmal bei der Erstellung angezeigt und kann später nicht mehr abgerufen werden.

Schlüsseltypen

Suchschlüssel generieren

Über das Dashboard

1. Navigieren Sie zu Suche → API-Schlüssel
2. Klicken Sie auf API-Schlüssel erstellen
3. Wählen Sie den Schlüsseltyp: Suche
4. Erlaubte Ursprünge konfigurieren (während der Entwicklung leer lassen)
5. Rate-Limit festlegen (Standard: 60 Req/Min)
6. Optionales Ablaufdatum festlegen
7. Klicken Sie auf Erstellen – kopieren Sie den Schlüssel sofort, er wird nicht erneut angezeigt

Über oRPC

const key = await orpc.search.createApiKey.call({
	organizationId: "org_...",
	indexSlug: "products",
	scopes: ["search"],
	allowedOrigins: ["https://yourstore.com"],
	rateLimitPerMinute: 60,
	name: "Storefront-Suchschlüssel",
});

console.log(key.plaintext); // ss_search_abc123... — jetzt speichern!

Connector-Schlüssel generieren

Connector-Schlüssel verwenden den Bereich connector_write und das Präfix ss_connector_*. Sie werden von CMS-Modulen verwendet, um Dokumente an den Ingest-Endpunkt zu übermitteln.

const key = await orpc.search.createConnectorToken.call({
	organizationId: "org_...",
	indexSlug: "products",
	name: "PrestaShop-Connector",
});

console.log(key.plaintext); // ss_connector_abc123...

Im Dashboard werden Connector-Schlüssel unter Connectoren → Connector-Token angezeigt.

Suchschlüssel verwenden

HTTP-Header

curl -X POST https://your-app.com/api/search \
  -H "Authorization: Bearer ss_search_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "indexSlug": "products", "q": "headphones" }'

Browser-SDK

import { AacSearchClient } from "@repo/search-client";

const client = new AacSearchClient({
	baseUrl: "https://your-app.com",
	apiKey: "ss_search_your_key",
	indexSlug: "products",
});

const results = await client.search({ q: "headphones" });

Siehe Browser-SDK für die vollständige SDK-Dokumentation.

Eingeschränkte Token

Eingeschränkte Token sind kurzlebige, HMAC-signierte Token, die die Berechtigungen eines Suchschlüssels einschränken. Sie werden serverseitig generiert und an den Browser übergeben – der Basis-Suchschlüssel verbleibt auf dem Server.

Häufiger Anwendungsfall: Suchergebnisse auf die aktuelle Organisation oder Preisstufe des Benutzers beschränken.

// Serverseitig: eingeschränktes Token generieren
const scopedToken = await orpc.search.createScopedToken.call({
	organizationId: "org_...",
	indexSlug: "products",
	scopedFilter: "availability:=in_stock && price:<100",
	expiresInSeconds: 3600,
});

// An Browser übergeben – wie einen regulären Suchschlüssel verwenden
// Der Filter wird mit etwaigen Aufruferfiltern UND-verknüpft

Eingeschränkte Token sind zustandslos (nicht in der DB gespeichert). Sie laufen basierend auf dem Parameter expiresInSeconds ab. Siehe Eingeschränkte Suchtoken für vollständige Details.

Ursprungsbeschränkung

Jeder Suchschlüssel hat eine allowedOrigins[]-Liste. Anfragen von nicht aufgelisteten Ursprüngen erhalten eine 403-Antwort.

• Entwicklung: allowedOrigins leer lassen, um alle Ursprünge zuzulassen
• Produktion: Ihre Storefront-Domains explizit hinzufügen

// Beispiel: Auf bestimmte Domains beschränken
allowedOrigins: ["https://mystore.com", "https://www.mystore.com"];

Free-Plan-Beschränkung: Im Free-Plan sind nur *.aacsearch.com-Subdomains in allowedOrigins erlaubt. Upgraden Sie auf Pro für die Unterstützung benutzerdefinierter Domains.

Rate-Limits

Standard-Rate-Limit: 60 Anfragen pro Minute pro Schlüssel. Bei Überschreitung wird zurückgegeben:

HTTP/1.1 429 Too Many Requests
Retry-After: 15

{ "error": "rate_limit_exceeded" }

Passen Sie Rate-Limits pro Schlüssel bei der Erstellung an oder aktualisieren Sie sie im Dashboard.

Schlüssel widerrufen

await orpc.search.revokeApiKey.call({
	organizationId: "org_...",
	keyId: "key_...",
});

Das Widerrufen eines Schlüssels ist sofort wirksam. Der Schlüssel wird bei der nächsten Anfrage abgelehnt. Der gehashte Wert wird in der Datenbank zu Audit-Log-Zwecken aufbewahrt.

Checkliste zur Schlüsselsicherheit

• Schlüssel niemals in die Versionskontrolle einchecken
• Schlüssel niemals protokollieren (AACsearch protokolliert sie serverseitig nie)
• ss_search_*-Schlüssel im Browser verwenden (schreibgeschützt, durch Ursprung begrenzt)
• ss_connector_*-Schlüssel nur im CMS-Modul verwenden (serverseitig)
• Schlüssel regelmäßig über den Widerrufen + Neu-Erstellen-Ablauf rotieren
• allowedOrigins für Produktionsschlüssel festlegen
• expiresAt für temporären Zugriff festlegen