> ## Documentation Index > Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt > Use this file to discover all available pages before exploring further. # Eine Partner-App mit OAuth registrieren und installierte Apps verwalten > Registrieren Sie eine OAuth-App, führen Sie Kunden durch den Zustimmungsbildschirm von Flowella, tauschen Sie Codes gegen Tokens und prüfen oder widerrufen Sie in Ihrer Organisation installierte Apps. Mit einer OAuth-App können andere Flowella-Organisationen Ihr Produkt mit ihrem Konto verbinden, ohne API-Schlüssel weiterzugeben. Jede Organisation genehmigt Ihre App auf einem Zustimmungsbildschirm und kann sie jederzeit widerrufen. Diese Seite zeigt Partnern, wie sie eine App registrieren und OAuth verwenden, und zeigt Kunden, wie sie installierte Apps prüfen und widerrufen. Für Ihre eigenen Skripte und Integrationen ist ein [API-Schlüssel](https://knowledge.flowella.io/de/settings/api-keys.md) einfacher. ## So funktioniert es Flowella unterstützt drei OAuth-Grants: Authorization Code mit PKCE für die Organisationen von Kunden, Client Credentials für Ihre eigene Organisation sowie Refresh Tokens. Der Ablauf zeigt, wie ein Kunde Ihre App mit dem Authorization-Code-Grant installiert. ```mermaid theme={null} sequenceDiagram participant Admin as Kunden-Admin participant App as Ihre App participant Flowella App->>Admin: Weiterleitung zur Flowella-Autorisierungs-URL Admin->>Flowella: Autorisierungs-URL öffnen Flowella->>Admin: Zustimmungsbildschirm anzeigen Admin->>Flowella: Allow access wählen Flowella->>App: Rückleitung mit einem Code App->>Flowella: Code und Verifier austauschen Flowella->>App: Access und Refresh Tokens App->>Flowella: API mit dem Access Token aufrufen ``` ## Bevor Sie beginnen * Sie benötigen die Rolle **Owner** oder **Admin** in der Organisation, der die App gehören soll. Andere Rollen sehen **Developer apps** im Menü, aber die Liste wird für sie nicht geladen. * Ihre App benötigt eine Callback-Adresse (Redirect URI), die den Autorisierungscode empfangen kann. * Ihre App muss bei jeder Autorisierungsanfrage einen `state`-Wert und eine mit `S256` erzeugte PKCE-`code_challenge` senden. ## Eine App registrieren **1. Developer apps öffnen** Gehen Sie zu **Settings** und wählen Sie in der Gruppe **Developer** die Option **Developer apps**. **2. Eine neue App beginnen** Wählen Sie **Create app**. Der Dialog **Create developer app** öffnet sich. **3. Die App benennen** Geben Sie unter **App name** den Namen ein, unter dem Kunden Ihr Produkt kennen, mit bis zu 120 Zeichen, zum Beispiel `Acme CRM connector`. **4. Redirect URIs hinzufügen** Geben Sie unter **Redirect URIs** jede Callback-Adresse in einer eigenen Zeile ein, bis zu 20. Bei der Autorisierung muss die `redirect_uri`, die Ihre App sendet, genau mit einer davon übereinstimmen. **5. Scopes wählen** Unter **Scopes** sind die Lese-Scopes bereits aktiviert. Aktivieren Sie alle weiteren Scopes, die Ihre App benötigt, und deaktivieren Sie die, die sie nicht benötigt. Mehr kann Ihre App nie anfordern. Siehe [Scopes](https://knowledge.flowella.io/de/api-reference/introduction.md#scopes). **6. Die App erstellen und das Secret kopieren** Wählen Sie **Create app**. Der Dialog **Save your client secret** zeigt das Client Secret an, das mit `flc_` beginnt. Wählen Sie **Copy**, speichern Sie das Secret auf Ihrem Server und wählen Sie dann **Done**. > [!WARNING] > > Flowella zeigt das Client Secret nur einmal an, und Sie können es nicht zurücksetzen. Wenn Sie es verlieren, müssen Sie die App löschen und eine neue registrieren, und jede Organisation, die Ihre App verwendet, muss die neue App genehmigen. Name, Redirect URIs und Scopes einer App lassen sich nach dem Erstellen nicht mehr ändern. Um sie zu ändern, registrieren Sie eine neue App. Die Liste **Developer apps** zeigt für jede App **Name**, **Client ID** (beginnt mit `floa_`), **Redirect URIs** und das Datum **Created** an, mit einer Schaltfläche **Delete** unter **Actions**. ## Einen Kunden durch die Autorisierung führen Leiten Sie den Browser des Kunden zum Autorisierungsendpunkt auf dem Host der Flowella-App: ```text theme={null} https://app.flowella.io/api/oauth/authorize?response_type=code&client_id=floa_xxxx&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&scope=messages%3Aread%20contacts%3Aread&state=RANDOM_STATE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256 ``` | Parameter | Erforderlich | Wert | | - | - | - | | `response_type` | Ja | `code` | | `client_id` | Ja | Die Client-ID Ihrer App. | | `redirect_uri` | Ja | Genau eine der registrierten Redirect URIs der App. | | `state` | Ja | Ein zufälliger Wert, den Ihre App prüft, wenn der Kunde zurückkehrt. | | `code_challenge` | Ja | Der base64url-codierte SHA-256-Hash eines zufälligen `code_verifier`, den Ihre App aufbewahrt. | | `code_challenge_method` | Nein | `S256`, die einzige unterstützte Methode und der Standard. | | `scope` | Nein | Durch Leerzeichen getrennte Scopes, alle innerhalb der Scopes der App. Ohne diesen Parameter erhält die App nur die Lese-Scopes, die ihr erlaubt sind. | | `publicOrgId` | Nein | Die sechsstellige Organisationsnummer aus der Flowella-Webadresse des Kunden. Ohne diesen Parameter verwendet Flowella die Organisation, in der die Person gerade arbeitet. | Ist die Anfrage ungültig, zeigt Flowella statt des Zustimmungsbildschirms einen Fehler an und leitet nicht weiter. Das passiert zum Beispiel, wenn die `redirect_uri` nicht übereinstimmt oder ein Scope nicht erlaubt ist. ### Was der Kunde sieht 1. Wenn die Person nicht angemeldet ist, fordert Flowella sie zuerst zur Anmeldung auf. 2. Die Person muss **Owner** oder **Admin** der Organisation sein. Alle anderen sehen den Fehler `Owner or admin role required to authorize apps`. 3. Der Bildschirm **Authorize app** zeigt Ihre **Client ID:** und die **Requested scopes:** an. Wenn Ihre App keinen `scope` gesendet hat, steht dort **This app will receive its default allowed scopes.** 4. Die Person wählt **Allow access** oder **Deny**. **Allow access** leitet den Browser zu Ihrer `redirect_uri` mit `code` und `state` im Query-String. Der Code ist 10 Minuten gültig und funktioniert einmal. **Deny** leitet den Browser zu Ihrer `redirect_uri` mit `error=access_denied`, einer `error_description` und Ihrem `state`. ## Den Code gegen Tokens tauschen Ihr Server tauscht den Code am Token-Endpunkt ein. Authentifizieren Sie sich mit Ihrer Client-ID und Ihrem Secret, entweder mit HTTP-Basic-Authentifizierung oder als `client_id` und `client_secret` im Body. Der Body kann formularcodiert oder JSON sein. ```bash theme={null} curl -X POST "https://app.flowella.io/api/oauth/token" \ -u "$FLOWELLA_CLIENT_ID:$FLOWELLA_CLIENT_SECRET" \ -d grant_type=authorization_code \ -d code="$CODE" \ -d redirect_uri="https://example.com/oauth/callback" \ -d code_verifier="$CODE_VERIFIER" ``` Die Antwort enthält die Tokens: ```json theme={null} { "access_token": "fla_xxxxxxxxxxxxxxxx", "token_type": "bearer", "expires_in": 3600, "refresh_token": "flr_xxxxxxxxxxxxxxxx", "scope": "messages:read contacts:read" } ``` | Token | Beginnt mit | Gültig für | | - | - | - | | Access Token | `fla_` | 1 Stunde | | Refresh Token | `flr_` | 30 Tage, und nur bis zur ersten Verwendung | Der Token-Endpunkt akzeptiert 30 Anfragen pro Minute für jede Client-ID und IP-Adresse. Darüber hinaus gibt er `429` mit einem Header `Retry-After` zurück. ## Die API aufrufen Senden Sie das Access Token als Bearer-Token, genau wie einen API-Schlüssel: ```http theme={null} Authorization: Bearer fla_xxxxxxxxxxxxxxxx ``` Das Token funktioniert nur für die Organisation, die es genehmigt hat, und nur für die gewährten Scopes. Eine Anfrage außerhalb dieser Scopes gibt `403 INSUFFICIENT_SCOPE` zurück. Jedes Access Token hat sein eigenes Ratenlimit. Siehe die [API-Einführung](https://knowledge.flowella.io/de/api-reference/introduction.md). > [!NOTE] > > `POST /v1/templates/send` akzeptiert nur API-Schlüssel und lehnt OAuth-Access-Tokens mit `401` ab. ### Ein Access Token erneuern Fordern Sie vor Ablauf des Access Tokens mit `grant_type=refresh_token`, dem `refresh_token` und Ihrer Client-Authentifizierung ein neues an. Die Antwort enthält ein neues Access Token und ein neues Refresh Token, und das alte Refresh Token funktioniert nicht mehr. Wenn jemand ein bereits verwendetes Refresh Token vorlegt, widerruft Flowella alle aus dieser Autorisierung ausgestellten Tokens, und der Kunde muss Ihre App erneut genehmigen. ### Auf Ihre eigene Organisation zugreifen Um die API für die Organisation aufzurufen, der die App gehört, verwenden Sie `grant_type=client_credentials` mit Ihrer Client-Authentifizierung und einem optionalen `scope`. Sie erhalten ein Access Token ohne Refresh Token. Ihre App erscheint dann unter **Installed apps** in Ihrer eigenen Organisation. ### Ein Token widerrufen oder prüfen | Endpunkt | Was er tut | | - | - | | `POST https://app.flowella.io/api/oauth/revoke` | Widerruft das gesendete `token` zusammen mit allen damit ausgestellten Tokens. | | `POST https://app.flowella.io/api/oauth/introspect` | Gibt zurück, ob das `token` `active` ist, mit seinem `scope`, `client_id`, `organization_id` und Ablaufzeitpunkt. | Beide Endpunkte benötigen Ihre Client-Authentifizierung. Das Discovery-Dokument unter `https://app.flowella.io/.well-known/oauth-authorization-server` listet alle Endpunkte und unterstützten Optionen auf. ## Installierte Apps prüfen und widerrufen Kunden verwalten die von ihnen genehmigten Apps unter **Installed apps**. Sie benötigen die Rolle **Owner** oder **Admin**. Die Liste zeigt: | Spalte | Was sie anzeigt | | - | - | | **App** | Den Namen der App mit ihrer Client-ID darunter. | | **Scopes** | Die Scopes, die der App gewährt wurden. | | **Installed** | Wann die App zum ersten Mal genehmigt wurde. | | **Actions** | **Revoke** oder ein Badge **Revoked**. | So widerrufen Sie eine App: 1. Gehen Sie zu **Settings** und wählen Sie in der Gruppe **Developer** die Option **Installed apps**. 2. Wählen Sie in der Zeile der App **Revoke**. 3. Bestätigen Sie die Abfrage **Revoke this install? Existing tokens stop working.** Die Tokens der App funktionieren sofort nicht mehr, und sie kann sie nicht erneuern. Die Zeile bleibt mit einem Badge **Revoked** in der Liste. Um der App wieder Zugriff zu geben, genehmigt ein Owner oder Admin sie erneut auf dem Zustimmungsbildschirm. > [!NOTE] > > Wenn Sie Ihre eigene App in Ihrer eigenen Organisation widerrufen, stoppt das den Client-Credentials-Grant nicht: Die App kann ein neues Token anfordern, wodurch die Installation wieder aktiviert wird. Um Ihre eigene App vollständig abzuschneiden, löschen Sie sie unter **Developer apps**. ## Eine App löschen Wählen Sie unter **Developer apps** in der Zeile der App **Delete** und bestätigen Sie **Delete this app and its tokens?** Flowella entfernt die App, ihre Installation in jeder Organisation, die sie genehmigt hat, und alle ihre Tokens. Dies lässt sich nicht rückgängig machen. ## Fehlerbehebung > **Could not load developer apps oder Could not load installed apps** > > Nur Owners und Admins können diese Bildschirme anzeigen. Bitten Sie einen Owner oder Admin, die App für Sie zu verwalten. Rollen lassen sich in der App nicht ändern: siehe [Die Rolle einer Person ändern](https://knowledge.flowella.io/de/settings/team.md#die-rolle-einer-person-ändern). > **Redirect URI stimmt nicht überein** > > Die `redirect_uri` in der Anfrage muss genau mit einer der registrierten Redirect URIs der App übereinstimmen, einschließlich Schema, Pfad und eines eventuellen abschließenden Schrägstrichs. Derselbe Wert muss beim Eintauschen des Codes erneut gesendet werden. Redirect URIs einer App lassen sich nicht bearbeiten, registrieren Sie daher eine neue App, wenn Sie eine andere benötigen. > **invalid\_scope** > > Ein angeforderter Scope ist falsch geschrieben oder gehört nicht zu den Scopes der App. Fordern Sie nur Scopes an, die Sie beim Registrieren der App aktiviert haben. > **Owner or admin role required to authorize apps** > > Die Person, die die App genehmigt, ist weder Owner noch Admin der Organisation. Bitten Sie einen Owner oder Admin, die Autorisierung abzuschließen. > **Der Code-Austausch schlägt fehl** > > Die Meldungen `Authorization code expired` und `Authorization code already used` bedeuten, dass Sie die Autorisierung neu starten müssen: Codes gelten 10 Minuten und funktionieren einmal. `PKCE verification failed` bedeutet, dass der `code_verifier` nicht zur gesendeten `code_challenge` passt. ## Verwandt > **[API-Einführung](https://knowledge.flowella.io/de/api-reference/introduction.md)** > > Authentifizierung, Scopes, Ratenlimits und Fehler. > **[Developer Hub](https://knowledge.flowella.io/de/settings/developer-hub.md)** > > Letzte API-Anfragen, Schnellstarts und die API-Sandbox. > **[API-Schlüssel](https://knowledge.flowella.io/de/settings/api-keys.md)** > > Einfacherer Zugriff für Ihre eigenen Skripte und Integrationen. > **[Webhooks-Referenz](https://knowledge.flowella.io/de/api-reference/webhooks.md)** > > Auf Ereignisse in den Organisationen reagieren, die Ihre App installieren. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.