Eine Partner-App mit OAuth registrieren und installierte Apps verwalten

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 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.

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

Developer apps öffnen

Gehen Sie zu Settings und wählen Sie in der Gruppe Developer die Option Developer apps.

Eine neue App beginnen

Wählen Sie Create app. Der Dialog Create developer app öffnet sich.

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.

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.

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.

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.

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:

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

Wenn die Person nicht angemeldet ist, fordert Flowella sie zuerst zur Anmeldung auf.
Die Person muss Owner oder Admin der Organisation sein. Alle anderen sehen den Fehler Owner or admin role required to authorize apps.
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.
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.

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:

{
  "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:

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.

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:

Gehen Sie zu Settings und wählen Sie in der Gruppe Developer die Option Installed apps.
Wählen Sie in der Zeile der App Revoke.
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.

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.

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

Authentifizierung, Scopes, Ratenlimits und Fehler.

Developer Hub

Letzte API-Anfragen, Schnellstarts und die API-Sandbox.

API-Schlüssel

Einfacherer Zugriff für Ihre eigenen Skripte und Integrationen.

Webhooks-Referenz

Auf Ereignisse in den Organisationen reagieren, die Ihre App installieren.

Erste Schritte

Grundlagen

App nutzen

Einstellungen

Meta- und WhatsApp-Einrichtung

HubSpot-Integration

Flows und Kampagnen

API-Referenz

Fehlerbehebung

Änderungsprotokoll

Eine Partner-App mit OAuth registrieren und installierte Apps verwalten

So funktioniert es

Bevor Sie beginnen

Eine App registrieren

Einen Kunden durch die Autorisierung führen

Was der Kunde sieht

Den Code gegen Tokens tauschen

Die API aufrufen

Ein Access Token erneuern

Auf Ihre eigene Organisation zugreifen

Ein Token widerrufen oder prüfen

Installierte Apps prüfen und widerrufen

Eine App löschen

Fehlerbehebung

Verwandt

API-Einführung

Developer Hub

API-Schlüssel

Webhooks-Referenz

​So funktioniert es

​Bevor Sie beginnen

​Eine App registrieren

​Einen Kunden durch die Autorisierung führen

​Was der Kunde sieht

​Den Code gegen Tokens tauschen

​Die API aufrufen

​Ein Access Token erneuern

​Auf Ihre eigene Organisation zugreifen

​Ein Token widerrufen oder prüfen

​Installierte Apps prüfen und widerrufen

​Eine App löschen

​Fehlerbehebung

​Verwandt

API-Einführung

Developer Hub

API-Schlüssel

Webhooks-Referenz

So funktioniert es

Bevor Sie beginnen

Eine App registrieren

Einen Kunden durch die Autorisierung führen

Was der Kunde sieht

Den Code gegen Tokens tauschen

Die API aufrufen

Ein Access Token erneuern

Auf Ihre eigene Organisation zugreifen

Ein Token widerrufen oder prüfen

Installierte Apps prüfen und widerrufen

Eine App löschen

Fehlerbehebung

Verwandt