Authentifizierung

Sicherer API-Zugriff mit organisationsgebundenen API-Keys. Jedes Deployment bedient genau eine Organisation, daher ist ein Key an diese eine Organisation gebunden und nicht an einen von mehreren Mandanten.

Format des API-Keys

Owlat validiert Keys anhand eines Live-Präfix-Formats:

lm_live_...

Auth-Header senden

curl "https://<deployment>.convex.site/api/v1/contacts" \
  -H "Authorization: Bearer lm_live_your_key"

Authorization: <api_key> (ohne Bearer) wird ebenfalls akzeptiert, empfohlen ist jedoch Bearer.

Häufige Auth-Fehler

Fehlender Header (`401`)

{
  "error": {
    "message": "Missing or invalid Authorization header. Use: Authorization: Bearer <api_key>",
    "category": "unauthenticated"
  }
}

Ungültiges Format (`401`)

{
  "error": {
    "message": "Invalid API key format",
    "category": "unauthenticated"
  }
}

Ungültiger oder widerrufener Key (`401`)

{
  "error": {
    "message": "Invalid API key",
    "category": "unauthenticated"
  }
}

Unzureichender Scope (`403`)

{
  "error": {
    "message": "This API key is missing the required scope: contacts:write",
    "category": "forbidden"
  }
}

Rate-Limit überschritten (`429`)

{
  "error": {
    "message": "Rate limit exceeded. Maximum 10 requests per second.",
    "category": "rate_limited"
  }
}

Das Limit ist ein Token-Bucket, der dauerhaft 10 Anfragen pro Sekunde trägt, kurze Bursts von bis zu 15 Anfragen aber zulässt, bevor gedrosselt wird.

Authentifizierte Antworten (einschließlich der 429 selbst) enthalten Rate-Limit-Header, damit Clients präzise zurückregeln können. Eine 429 enthält zusätzlich Retry-After. Authentifizierungsfehler (401) enthalten diese Header nicht.

Header	Bedeutung
`X-RateLimit-Limit`	Dauerhaft zulässige Anfragen pro Sekunde
`X-RateLimit-Remaining`	Im aktuellen Fenster verbleibende Anfragen
`X-RateLimit-Reset`	Unix-Zeitstempel (Sekunden), zu dem das Fenster zurückgesetzt wird
`Retry-After`	Wartezeit in Sekunden vor einem erneuten Versuch (nur bei `429`)

Scopes

Jeder Key trägt eine Menge von Scopes, die festlegen, welche v1-Endpunkte er aufrufen darf. Eine Anfrage mit einem Key, dem der erforderliche Scope fehlt, wird mit 403 forbidden abgelehnt (siehe oben).

Scope	Erlaubt
`contacts:read`	`GET /api/v1/contacts`, `GET /api/v1/contacts/{id}`
`contacts:write`	Kontakte anlegen / aktualisieren / löschen
`events:write`	`POST /api/v1/events`
`transactional:send`	`POST /api/v1/transactional`
`topics:write`	einen Kontakt zu einem Thema hinzufügen / entfernen

Das Anlegen eines Keys erfordert eine explizite, nicht leere Scope-Liste — wird sie weggelassen, wird die Anfrage abgelehnt, und unbekannte Scope-Namen werden ebenfalls abgelehnt. Bereits vorhandene Keys ohne gespeicherte Scopes werden so behandelt, als hätten sie keine (Deny-all); vergeben Sie daher gezielt die Scopes, die jede Integration benötigt.

Best Practices

Keys ausschließlich serverseitig halten
Keys planmäßig rotieren und widerrufen
Pro Umgebung eigene Keys verwenden
Anfragemuster und Fehler überwachen