Authentifizierung

Jede Anfrage an die CodeCourier REST API muss mit einem projektbezogenen API-Schlüssel authentifiziert werden. Diese Seite erklärt, wie Sie Schlüssel erstellen, wie Sie sie in Anfragen einbinden und wie Sie Authentifizierungsfehler behandeln.

API-Schlüssel erstellen

1. Öffnen Sie Ihr Projekt im CodeCourier-Dashboard.
2. Navigieren Sie zu Projekteinstellungen und öffnen Sie den Bereich API-Schlüssel.
3. Klicken Sie auf Neuen Schlüssel erzeugenund vergeben Sie einen aussagekräftigen Namen (z. B. "CI Pipeline" oder "LLM Agent").
4. Das System zeigt den vollständigen Schlüssel genau einmal an. Kopieren Sie ihn sofort und speichern Sie ihn sicher. CodeCourier speichert nur einen SHA-256-Hash -- der Klartext-Schlüssel kann nicht wiederhergestellt werden.

Sie können Schlüssel auch programmatisch über die Project API erzeugen: POST /api/v1/project/api-keys/generate.

API-Schlüssel-Format

Alle Projekt-API-Schlüssel folgen einem erkennbaren Präfix-Format:

cc_live_a1b2c3d4e5f6...   # production key
cc_test_a1b2c3d4e5f6...   # test/staging key

Schlüssel werden mit cc_live_ (Produktion) oder cc_test_ (Testumgebungen) präfigiert. Das Präfix zusammen mit den ersten 8 Zeichen dient als im Dashboard angezeigtes Anzeige-Präfix. Der vollständige Schlüssel ist eine lange, zufällige Zeichenkette, die zur Authentifizierung verwendet wird.

API-Schlüssel verwenden

Übergeben Sie den Schlüssel als Bearer Token im Authorization-Header jeder Anfrage:

curl -X GET \
  -H "Authorization: Bearer cc_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  https://<your-deployment>.convex.site/api/v1/project

Für POST-Anfragen mit JSON-Body:

curl -X POST \
  -H "Authorization: Bearer cc_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{"name": "My Workflow"}' \
  https://<your-deployment>.convex.site/api/v1/workflows/create

Basis-URL

Die Basis-URL ist der HTTP-Actions-Endpunkt Ihres Convex-Deployments:

https://<your-deployment>.convex.site/api/v1/

Häufiger Fehler: Verwenden Sie .convex.site -- NICHT .convex.cloud. Die Domain .convex.cloud ist die interne Convex-Daten-WebSocket-URL und verarbeitet keine REST-API-Anfragen. Nur .convex.site stellt HTTP Actions bereit.

Ihren Deployment-Namen finden Sie im Convex-Dashboard (z. B. happy-animal-123), was eine Basis-URL von https://happy-animal-123.convex.site/api/v1/ ergibt.

Schlüsseleigenschaften

• Projektbezogen -- Jeder Schlüssel ist an ein konkretes Projekt gebunden und kann nur auf Ressourcen innerhalb dieses Projekts zugreifen.
• Benannt -- Vergeben Sie menschenlesbare Namen für eine einfache Verwaltung.
• Widerrufbar -- Schlüssel können sofort widerrufen werden. Widerrufene Schlüssel authentifizieren ab sofort nicht mehr.
• Nutzungs-getrackt -- Der Zeitstempel lastUsedAt wird bei jeder Verwendung aktualisiert und hilft dabei, ungenutzte Schlüssel zu identifizieren.

Antwortformat

Alle API-Antworten verwenden einen konsistenten JSON-Envelope:

Erfolgsantwort

{
  "data": {
    "id": "abc123",
    "name": "My Project",
    ...
  }
}

Fehlerantwort

{
  "error": "Human-readable error message"
}

Fehlercodes

• 400 Bad Request -- Fehlende Pflichtfelder, ungültiger JSON-Body oder ungültige Query-Parameter.
• 403 Forbidden -- Ungültiger API-Schlüssel, widerrufener Schlüssel oder Schlüssel hat keinen Zugriff auf das angeforderte Projekt.
• 404 Not Found -- Die angeforderte Ressource existiert nicht oder wurde dauerhaft gelöscht.
• 500 Internal Server Error -- Ein unerwarteter Fehler ist aufgetreten. Die Fehlermeldung ist im Antwort-Body enthalten.

Schlüssel über die API verwalten

Die API selbst stellt Endpunkte zur Schlüsselverwaltung bereit (Sie benötigen einen existierenden Schlüssel, um diese zu verwenden):

• GET /api/v1/project/api-keys -- Alle Schlüssel des Projekts auflisten (zeigt Präfix, Name, Datumsangaben, Status).
• POST /api/v1/project/api-keys/generate -- Neuen Schlüssel erzeugen. Body: { "name": "Key Name" }. Liefert den vollständigen Schlüssel (einziger Zeitpunkt, an dem er angezeigt wird).
• POST /api/v1/project/api-keys/revoke -- Schlüssel widerrufen. Body: { "keyId": "..." }.

Provider-API-Schlüssel

Getrennt von den Projekt-API-Schlüsseln verwaltet CodeCourier Provider-Schlüssel für externe Dienste, die zur Laufzeit der Sandbox verwendet werden (E2B, Anthropic, OpenRouter, OpenAI, GitHub). Diese werden über die Endpunkte /api/v1/project/provider-keys/* konfiguriert. Alle Provider-Schlüssel werden vor der Speicherung verschlüsselt; nur die letzten vier Zeichen werden zur Anzeige im Klartext gespeichert.

Sicherheits-Best-Practices

• API-Schlüssel niemals in die Versionskontrolle einchecken. Verwenden Sie Umgebungsvariablen oder einen Secrets-Manager.
• Schlüssel regelmäßig rotieren. Widerrufen und erzeugen Sie Schlüssel periodisch neu. Das Feld lastUsedAt hilft dabei, verdächtige Aktivität zu erkennen.
• Verwenden Sie aussagekräftige Namen.Benennen Sie Schlüssel nach ihrem Anwendungsfall (z. B. "CI Pipeline", "Staging Agent"), damit Sie wissen, welcher zu widerrufen ist, wenn er kompromittiert wurde.
• Ungenutzte Schlüssel widerrufen. Schlüssel, die seit Monaten nicht mehr verwendet wurden, sollten widerrufen werden.