> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Partnerintegrationen für Outposts

> Einen Outpost von einer Partnerplattform mit einem PKCE-Codeaustausch verbinden

<Note>
  Vorläufige Hinweise — dieser Ablauf befindet sich noch in einer frühen
  Entwicklungsphase, und die folgenden Details können sich ändern.
</Note>

Partnerplattformen (z. B. Compute-Anbieter) können im Namen eines Kunden einen Outpost verbinden. Der Devin-Admin des Kunden autorisiert die Verbindung im Browser; Devin erstellt dann einen Outpost und einen Service-Benutzer und übergibt dem Partner ein Token, mit dem Worker für den Outpost ausgeführt werden können.

Der Ablauf ist ein leichtgewichtiger OAuth-Autorisierungscode-Austausch mit [PKCE](https://datatracker.ietf.org/doc/html/rfc7636). Über den Browser wird dabei nur ein kurzlebiger **Code** zur einmaligen Verwendung übertragen — das Token des Service-Benutzers wird im Server-zu-Server-Austausch ausgetauscht und läuft nie über den Browser.

<div id="prerequisites">
  ## Voraussetzungen
</div>

* **Callback-Allowlist.** Jede `callback_url`, die Sie verwenden, muss auf Devins Allowlist für Ihre Integration stehen. Diese wird von Cognition konfiguriert — senden Sie uns die genauen URLs vorab. Eine URL, die nicht auf der Liste steht, wird abgelehnt.
* **Outposts aktiviert.** Outposts muss für das Konto des Kunden aktiviert sein.
* **Admin-Autorisierung.** Für die Autorisierung einer Verbindung ist ein Devin-Admin erforderlich, der sowohl über Rechte für enterprise-settings als auch für die Verwaltung von Service-Benutzern verfügt. Der Partner benötigt niemals ein Devin-Token — der Admin autorisiert die Verbindung in seiner eigenen Browser-Sitzung.

<div id="flow-overview">
  ## Ablauf im Überblick
</div>

```
Partner backend                 Admin's browser                 Devin
     │                                │                            │
     │ 1. gen code_verifier,          │                            │
     │    derive code_challenge       │                            │
     │ 2. redirect to app.devin.ai/outposts/connect?…code_challenge│
     │───────────────────────────────>                            │
     │                                │ 3. admin confirms, "Connect"│
     │                                │──────confirm connection──────>
     │                                │ 4. redirect callback_url?code=…  │
     │<───────────────────────────────                            │
     │ 5. POST /outposts/connection-token  (code + code_verifier) │
     │────────────────────────────────────────────────────────────>
     │ 6. { access_token, api_base_url, … }                       │
     │<────────────────────────────────────────────────────────────
     │ 7. run outpost workers with access_token                   │
```

<div id="1-generate-a-pkce-verifier-and-challenge">
  ### 1. Einen PKCE-Verifier und eine Challenge generieren
</div>

In Ihrem Backend für jeden Verbindungsversuch:

* Generieren Sie einen zufälligen **`code_verifier`** mit hoher Entropie: 43–128 Zeichen aus dem nicht reservierten Alphabet `[A-Za-z0-9-._~]` (z. B. `base64url(random 32 bytes)` ohne Padding).
* Leiten Sie den **`code_challenge`** als ungefülltes base64url des SHA-256-Hashs des Verifiers ab (PKCE "S256"):

```python theme={null}
import base64, hashlib, secrets

code_verifier = secrets.token_urlsafe(32)  # 43+ Zeichen, nicht reserviertes Alphabet
code_challenge = (
    base64.urlsafe_b64encode(hashlib.sha256(code_verifier.encode()).digest())
    .rstrip(b"=")
    .decode()
)
```

Speichern Sie den `code_verifier` serverseitig (verknüpft mit dem Wert, den Sie verwenden, um den späteren Callback zuzuordnen). Senden Sie den Verifier niemals an den Browser — nur die Challenge verlässt Ihr Backend.

<div id="2-redirect-the-admin-to-the-connect-page">
  ### 2. Leiten Sie den Admin zur Connect-Seite weiter
</div>

Leiten Sie den Admin des Kunden mit der Challenge und Ihrem Callback an Devins Connect-Seite weiter:

```
https://app.devin.ai/outposts/connect
  ?callback_url=https://partner.example.com/devin/outpost-callback
  &outpost_name=my-outpost
  &outpost_image=https://partner.example.com/logo.png
  &platform=linux
  &code_challenge=<code_challenge>
```

| Parameter        | Erforderlich | Hinweise                                                                                                 |
| ---------------- | ------------ | -------------------------------------------------------------------------------------------------------- |
| `callback_url`   | ja           | URL, an die Devin den Einmalcode sendet. Muss auf Ihrer Allowlist stehen.                                |
| `code_challenge` | ja           | Die PKCE-S256-Challenge aus Schritt 1.                                                                   |
| `outpost_name`   | nein         | Vorgeschlagener Outpost-Name. Der Administrator kann ihn vor der Bestätigung bearbeiten.                 |
| `outpost_image`  | nein         | URL eines PNG-Symbols, das den Outpost repräsentiert, z. B. Ihr Firmenlogo.                              |
| `platform`       | nein         | Vorab ausgewählte Outpost-Plattform: `macos`, `linux` oder `windows`. Der Administrator kann sie ändern. |

Wenn der Administrator nicht angemeldet ist, speichert die Connect-Seite diese Parameter und fordert ihn zunächst zur Anmeldung auf; danach wird der Vorgang fortgesetzt.

<div id="3-admin-confirms">
  ### 3. Admin bestätigt
</div>

Die Connect-Seite zeigt eine Bestätigung mit einem bearbeitbaren Outpost-Namen und der Plattform an (sowie Ihrem `outpost_image`, falls vorhanden). Wenn der Admin auf **Connect** klickt, prüft Devin die Berechtigungen, die Callback-Allowlist und ob der Outpost-Name noch verfügbar ist, speichert dann einen verschlüsselten Einmalcode (TTL von 10 Minuten) und leitet dann mit dem Einmalcode zurück an Ihre App weiter.

Es gibt noch keinen Outpost oder Service-Benutzer — sie werden erst erstellt, wenn der Code eingelöst wird (Schritt 5). Ein noch nicht eingelöster Code verfällt einfach.

<div id="4-devin-redirects-the-code-to-your-callback">
  ### 4. Devin leitet den Code an Ihre Callback-URL weiter
</div>

Der Browser wird zu Ihrer `callback_url` weitergeleitet, wobei der Code angehängt wird:

```
https://partner.example.com/devin/outpost-callback?code=<one-time code>
```

<div id="5-exchange-the-code-server-to-server">
  ### 5. Tauschen Sie den Code Server-zu-Server aus
</div>

Rufen Sie in Ihrem Backend den `code_verifier` ab, den Sie in Schritt 1 gespeichert haben, und tauschen Sie den Code am Token-Endpunkt ein. Dies ist eine formularcodierte Token-Anfrage im OAuth-Stil:

```bash theme={null}
curl -X POST "https://api.devin.ai/outposts/connection-token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=<one-time code>" \
  --data-urlencode "code_verifier=<code_verifier>"
```

Dieser Endpunkt erfordert keine Devin-Authentifizierung — als Nachweis gilt der Besitz des Codes zusammen mit dem passenden PKCE-Verifier. Das ist bewusst ohne Authentifizierung umgesetzt: Der Code ist nur einmal verwendbar (wird atomar verbraucht), kurzlebig und an Ihre Challenge gebunden.

<div id="6-receive-the-credentials">
  ### 6. Anmeldedaten erhalten
</div>

Bei Erfolg erstellt Devin den Outpost und einen Service-Benutzer, dessen Geltungsbereich auf das Ausführen des Outpost-Workers beschränkt ist, und gibt Folgendes zurück:

```json theme={null}
{
  "outpost_id": "...",
  "account_id": "...",
  "outpost_name": "my-outpost",
  "service_user_id": "...",
  "api_base_url": "https://api.devin.ai",
  "access_token": "cog_...",
  "token_type": "bearer"
}
```

Antworten enthalten `Cache-Control: no-store` — zwischenspeichern Sie sie nicht.

<div id="7-run-outpost-workers">
  ### 7. Outpost-Worker ausführen
</div>

Speichern Sie `access_token` und `api_base_url` sicher und verwenden Sie `access_token` als Bearer-Credential, um Outpost-Worker für den Outpost auszuführen.

<div id="error-handling">
  ## Fehlerbehandlung
</div>

Der Token-Endpunkt folgt [RFC 6749 §5.2](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2). Bei einem unbekannten, abgelaufenen, bereits eingelösten (wiederverwendeten) oder nicht mit PKCE übereinstimmenden Code wird `400` zurückgegeben:

```json theme={null}
{
  "error": "invalid_grant",
  "error_description": "Invalid or expired connection code"
}
```

Da Codes nur einmal verwendet werden können und nach 10 Minuten ablaufen, behandeln Sie jedes `invalid_grant` als endgültigen Fehler: Verwerfen Sie den gespeicherten `code_verifier` und starten Sie den Ablauf erneut ab Schritt 1.

<div id="security-notes">
  ## Sicherheitshinweise
</div>

* **Das Token gelangt nie in den Browser.** Per Redirect wird nur der Einmalcode weitergeleitet; das Token des Service-Benutzers wird ausschließlich beim Server-zu-Server-Austausch zurückgegeben.
* **PKCE bindet den Code an Sie.** Ohne den `code_verifier`, der nur in Ihrem Backend vorliegt, ist der Code wertlos. Den Redirect (oder den Code) abzufangen, reicht also nicht aus, um ihn einzulösen.
* **Einmalcodes sind nur einmal verwendbar und kurzlebig.** Beim Einlösen wird der Code atomar verbraucht; außerdem verfällt er nach 10 Minuten.
* **Callback-URLs sind allowlistet.** Devin leitet einen Code nur an eine `callback_url` weiter, die Cognition vorab für Ihre Integration freigegeben hat.
* **Vergewissern Sie sich, dass der Code für den anfragenden Nutzer bestimmt ist.** Bestätigen Sie, dass der an Ihren Callback zurückgegebene Code zu demselben Nutzer gehört, der die Verbindung ursprünglich angefordert hat. Dadurch wird verhindert, dass ein Angreifer einen Nutzer dazu bringt, Devin unbemerkt an eine Sandbox zu binden, die der Angreifer kontrolliert.
* **Wählen Sie für `outpost_name` einen sinnvollen Wert.** Der Admin kann ihn überschreiben; der von Ihnen übergebene Name ist nur ein Vorschlag.