Embed-Session

POST /api/v1/embed/session
Authorization: Bearer aac_live_…

Ein aac_live_…-Schlüssel darf niemals in einen Browser gelangen. Dieser Endpunkt existiert genau dafür: Er tauscht den Schlüssel gegen ein Embed-Session-Token, beschränkt auf einen Index, eine Aktion (search:read) und eine Laufzeit. Das Token kommt auf die Seite (data-aac-token); der Schlüssel bleibt auf Ihrem Server.

Ein GET /embed/bootstrap und eine ?key=-Variante gibt es nicht. Ein Schlüssel in einer Query-Zeichenfolge, einem data--Attribut oder im HTML der Seite ist genau das Leck, das dieses Design beseitigt: Der Endpunkt liest den Schlüssel nur aus dem Authorization-Header und antwortet sonst mit 401 UNAUTHORIZED.

Rufen Sie ihn aus Ihrem eigenen Backend auf — Route-Handler, SSR-Durchlauf oder Build-Schritt — und reichen Sie das resultierende token an die Seite weiter.

Session ausstellenCopy Anchor Link

curl -sS -X POST "$AAC_API/embed/session" \
  -H "Authorization: Bearer $AAC_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "index": "documentation", "expires_in": 900 }'

Der Body ist optional. Ein nicht numerisches expires_in oder ein zu langer index ergibt 422 VALIDATION_ERROR.

{
	"ok": true,
	"token": "aac_sess_…",
	"token_type": "embed_session",
	"scope": ["search:read"],
	"index": { "slug": "documentation", "name": "Documentation" },
	"expires_at": "2026-10-23T11:15:02.000Z",
	"expires_in": 900,
	"settings": {
		"placeholder": "Dokumentation durchsuchen…",
		"perPage": 8,
		"queryBy": "title,content",
		"facets": ["category"],
		"showStats": true,
		"showRecent": true,
		"showVoice": false,
		"showImage": false,
		"showRelated": false,
		"accent": "#2563eb",
		"dark": false,
		"sortOptions": [
			{ "label": "Relevanz", "value": "default" },
			{ "label": "Neueste zuerst", "value": "created_at:desc" }
		]
	},
	"ui": { "name": "AACSearch UI", "version": "1.0.0" },
	"request_id": "req_4a6c8e0b2d4f6a8c0e2b4d6f"
}

Was die Antwort garantiert:

• Das Token ist nur zum Suchen. Es trägt search:read und sonst nichts, kann also weder schreiben noch löschen noch reindexieren. Wird die Seite kompromittiert, erbeutet man ein Credential, das von selbst abläuft und nur liest, was die Seite ohnehin anzeigt.
• Das Token ist an einen Index und einen Mandanten gebunden. Der Mandantenfilter wird bei jeder Anfrage serverseitig angewendet; der Browser sieht weder einen Infrastrukturschlüssel noch Host oder Collection-Namen.
• Es läuft ab. Standard 900 Sekunden, höchstens 3600. Für langlebige Seiten rechtzeitig ein neues ausstellen; ein abgelaufenes Token ergibt 401 EMBED_SESSION_EXPIRED.
• Es wird nicht gecacht. Antworten tragen cache-control: no-store; jede Ausstellung landet im Audit-Log (embed.session.issue).
• Einstellungen sind live. settings stammt aus SearchIndex.settings.embed; eine Änderung im Panel „Erscheinungsbild“ der Konsole ist beim nächsten Seitenaufruf sichtbar — ohne Redeploy.

Origin-AllowlistCopy Anchor Link

Hat der Schlüssel allowedOrigins, ergibt ein Browser-Aufruf von einem anderen Origin 403 ORIGIN_NOT_ALLOWED und erhält keine CORS-Header. Eine leere Liste bedeutet „jeder Origin“. Da der Session-Endpunkt aus Ihrem Backend aufgerufen werden soll, trägt ein Server-zu-Server-Aufruf keinen Origin-Header und wird nicht geprüft.

EinstellungenCopy Anchor Link

FehlerCopy Anchor Link

{
	"error": {
		"code": "UNAUTHORIZED",
		"message": "Send the API key as an Authorization header; embed sessions cannot be minted from a query parameter",
		"request_id": "req_7b9d1f3a5c7e9b1d3f5a7c9e"
	}
}

Endpunkte, die das Token akzeptierenCopy Anchor Link

Hält die Seite ein Token, spricht das Widget nur noch mit diesen Endpunkten. Alle authentifizieren sich mit dem Token — im JSON-Body (token) oder, wo angegeben, als Authorization: Bearer aac_sess_… — nie mit einem API-Schlüssel. Jeder beantwortet außerdem einen CORS-Preflight (OPTIONS) mit 204.

Die Suche über den Proxy durchläuft dieselbe Pipeline wie die öffentliche API (Query-Log, Regeln, Defaults, Relaxation, Did-you-mean); die Analytics sehen also den Widget-Traffic. Jede Embed-Suche zählt gegen das searches-Kontingent des Mandanten.

Token-Fehler an diesen Endpunkten:

BrowserzugriffCopy Anchor Link

Verwenden Sie POST /embed/session und /embed/search für das Widget oder eine eigene Browseroberfläche. Ihr Server tauscht den API-Schlüssel gegen ein kurzlebiges Token; der Browser erhält keine Infrastruktur-Zugangsdaten oder Speichernamen. Der erweiterte Endpunkt /scoped-key wird vom Widget nicht verwendet und ersetzt die Such-API der Plattform nicht.