Skip to main content
Die Devin API verwendet ein Principal + Token-Modell. Ein Principal ist, wer Sie sind (Ihre Identität), und ein Token ist, wie Sie das nachweisen (Ihr Berechtigungsnachweis). Diese Unterscheidung zu verstehen, ist der Schlüssel zur Wahl der richtigen Authentifizierungsmethode für Ihren Anwendungsfall.

​
Principals & Token

Alle API-Zugangsdaten verwenden das Präfixformat cog_. Fügen Sie Ihr Token in den Authorization-Header jeder Anfrage ein:
Der entscheidende Unterschied ist, als welcher Principal das Token authentifiziert:
  • Ein Service User API Key authentifiziert als der Service-Benutzer — es gelten die Identität, Berechtigungen und Org-Mitgliedschaften des Service-Benutzers.
  • Ein Personal Access Token authentifiziert als der menschliche Nutzer, der ihn erstellt hat — es gelten die Identität, Berechtigungen und Org-Mitgliedschaften dieses Nutzers.
Service-Benutzer sind nicht von Menschen genutzte Konten, die für API-Integrationen vorgesehen sind. Ihnen können über RBAC spezifische Berechtigungen zugewiesen werden, und sie können unabhängig von menschlichen Nutzern zu Organisationen hinzugefügt werden.

​
So funktioniert es

  1. Erstellen Sie einen Service-Benutzer unter Settings > Service users (Organisation) oder Enterprise settings > Service users (Enterprise)
  2. Weisen Sie eine Rolle zu, die steuert, auf welche Endpunkte der Service-Benutzer zugreifen kann
  3. Generieren Sie einen API-Key — der Schlüssel beginnt mit cog_ und wird bei der Erstellung nur einmal angezeigt
  4. Verwenden Sie den Schlüssel im Authorization-Header jeder API-Anfrage

​
Service-Benutzer-Geltungsbereiche

Ihre Organization-ID finden Sie auf der Seite Settings > Service Users.

​
Sitzungszuordnung mit create_as_user_id

Service-Benutzer sind separate Identitäten von menschlichen Nutzern. Standardmäßig werden Sitzungen, die von einem Service-Benutzer erstellt werden, dem Service-Benutzer selbst zugeordnet. Um Sitzungen im Namen eines bestimmten Nutzers zu erstellen, übergeben Sie beim Erstellen einer Sitzung den Parameter create_as_user_id. Die Sitzung erscheint dann in der Sitzungsliste dieses Nutzers und wird auf seine Nutzung angerechnet. Dafür ist die Berechtigung ImpersonateOrgSessions in der Rolle des Service-Benutzers erforderlich.

​
Wichtige Eigenschaften

  • Schlüssel beginnen mit cog_ und werden nur einmal bei der Erstellung angezeigt
  • Service-Benutzer werden in Audit-Protokollen getrennt von menschlichen Benutzern aufgeführt
  • Berechtigungen werden über RBAC gesteuert – weisen Sie nur die Berechtigungen zu, die die Integration benötigt
  • Enterprise-Service-Benutzer erben organisationsweite Berechtigungen über alle Organisationen hinweg
Ausführliche Einrichtungshinweise finden Sie im Schnellstart für Teams oder im Schnellstart für Enterprise.

​
Personal Access Tokens (geschlossene Beta)

Personal Access Tokens befinden sich derzeit in der geschlossenen Beta und sind per Feature-Flag aktiviert. Kontaktieren Sie den Support, um Zugriff zu erhalten. PATs sind für SSO-/Enterprise-Konten nicht verfügbar.
Personal Access Tokens (PATs) ermöglichen es menschlichen Nutzern, sich programmatisch mit ihrer eigenen Identität zu authentifizieren. Wenn Sie ein PAT verwenden, sieht die API Sie — Ihre Berechtigungen, Ihre org-Mitgliedschaften und Ihren Audit-Trail. Das ist nützlich, wenn Sie API-Aufrufe als Sie selbst ausführen möchten (z. B. für persönliche Skripte oder lokale Tools) statt über einen gemeinsam genutzten Service-Benutzer. Weitere Informationen finden Sie unter Personal Access Tokens.

​
Legacy-Authentifizierung (veraltet)

Legacy-API-Keys sind veraltet. Verwenden Sie API v3 mit Service-Benutzer-Authentifizierung. Siehe den Migrationsleitfaden.
Legacy-API-Keys werden mit den v1- und v2-APIs verwendet. Sie funktionieren während des Abschreibungszeitraums weiter, unterstützen jedoch keine neuen Funktionen wie RBAC, Sitzungszuordnung oder cursorbasierte Paginierung. Wo zu erstellen: Settings > API Keys

​
Best Practices zur Sicherheit

Geben Sie API-Schlüssel niemals in öffentlich zugänglichen Bereichen weiter, z. B. in GitHub-Repositories, clientseitigem Code oder Logs.
  1. Schlüssel sicher speichern: Verwenden Sie Umgebungsvariablen oder Systeme zum Secret-Management
  2. Schlüssel regelmäßig erneuern: Generieren Sie regelmäßig neue Schlüssel und widerrufen Sie alte
  3. Service-User für Automatisierung verwenden: Bevorzugen Sie Service-User gegenüber persönlichen Schlüsseln in Produktionsumgebungen
  4. Least-Privilege-Prinzip anwenden: Gewähren Sie nur die minimal erforderlichen Berechtigungen
  5. Nutzung überwachen: Prüfen Sie Audit-Logs auf unerwartete API-Aktivitäten
  6. Kompromittierte Schlüssel sofort widerrufen: Wenn ein Schlüssel offengelegt wurde, widerrufen Sie ihn und generieren Sie einen neuen

​
Fehlerbehebung

​
401 Unauthorized

Mögliche Ursachen:
  • Ungültige oder abgelaufene API key
  • Fehlender Authorization-Header
  • Falsches Bearer-Token-Format
  • Verwendung einer legacy API key (apk_ / apk_user_) mit Devin MCP — nur Schlüssel mit dem Präfix cog_ werden unterstützt
Lösung: Stellen Sie sicher, dass Ihre API key gültig ist und im Authorization-Header korrekt formatiert ist. Stellen Sie bei der MCP-Nutzung sicher, dass Sie eine API key eines Service-Benutzers verwenden (keinen legacy key).

​
403 Forbidden

Mögliche Ursachen:
  • Der API key verfügt nicht über die erforderlichen Berechtigungen
  • Du verwendest den falschen Schlüsseltyp für den Endpoint (z. B. Legacy-Schlüssel mit v3-Endpoints)
  • Du versuchst, auf Ressourcen außerhalb deines Zugriffsbereichs zuzugreifen
Lösung:
  • Stelle sicher, dass dein Servicebenutzer die richtige Rolle und die erforderlichen Berechtigungen hat
  • Für Legacy-v2-Endpoints: Stelle sicher, dass du die Enterprise-Admin-Rolle hast
  • Für Legacy-v1-Endpoints: Überprüfe, ob du Zugriff auf die Organisation hast

​
404 Nicht gefunden

Mögliche Ursachen:
  • Falsche API-Endpunkt-URL
  • Ressource existiert nicht oder Sie haben keinen Zugriff
Lösung: Überprüfen Sie die Endpunkt-URL und ob die Ressource existiert.

​
Nächste Schritte