OAuth-Apps: „Mit Sayweek verbinden“ in deiner eigenen App

Du willst einen „Mit Sayweek verbinden“-Button in dein Produkt, dein Agentur-Tool oder das System eines Kunden einbauen? Registriere eine OAuth-App. Jeder Sayweek-Nutzer kann sie mit seinem eigenen Workspace verbinden: Eine Zustimmungsseite zeigt, was die App anfragt, und ein Klick erlaubt es. Niemand muss einen API-Schlüssel kopieren.

App registrieren

1. 1Öffne Einstellungen → Alle Integrationen und klick auf die Karte REST API (Inhaberrechte und ein Tarif mit API nötig).
2. 2Klick unter OAuth-Apps auf App registrieren.
3. 3Gib den Name der App ein – den sehen die Nutzer; das Wort „Sayweek“ darf nicht darin vorkommen. Logo und Website müssen https://-Adressen sein.
4. 4Trag unter Weiterleitungs-URLs eine Adresse pro Zeile ein: https://, zum Entwickeln auch http://localhost oder http://127.0.0.1. Sie muss exakt übereinstimmen.
5. 5Wähle unter Was darf die App anfragen? die Berechtigungen und unter App-Typ serverseitig oder Browser/Mobil.
6. 6Klick auf Speichern und kopiere die Client-ID und das Client-Secret – nur jetzt sichtbar (bei Apps mit Secret).

Serverseitig oder öffentlicher Client?

• Serverseitig (mit Secret) – dein Server tauscht den Code mit dem Client-Secret und PKCE ein. Bewahre das Secret auf dem Server auf, nie im Browser oder in der App.
• Browser, Mobil oder CLI (ohne Secret) – kann kein Secret geheim halten, deshalb schützt nur PKCE. Brauchst du später doch ein Secret, macht Neues Secret daraus eine vertrauliche App.

So läuft das Verbinden

1. 1Schick den Nutzer an /oauth/authorize mit response_type=code, client_id, redirect_uri, scope (z. B. read write), state und für PKCE code_challenge + code_challenge_method=S256.
2. 2Der Nutzer meldet sich bei Sayweek an und sieht auf der Zustimmungsseite Namen, Logo und angefragte Berechtigungen deiner App – und kann sie einschränken.
3. 3Nach der Zustimmung leiten wir mit einem einmaligen code (10 Minuten gültig) an deine redirect_uri zurück.
4. 4Dein Server tauscht den Code bei /api/oauth/token mit dem code_verifier (und dem Secret) ein: Du bekommst einen Access-Token für 1 Stunde und einen Refresh-Token für 30 Tage. Beim Erneuern gibt es neue – der alte Refresh-Token ist danach unbrauchbar.

Berechtigungen

• read – Lesen: Marken, Kanäle, Wochenplan, Posts, Ideen, Statistik.
• write – Entwürfe und Ideen: schreibt und bearbeitet Entwürfe ohne Veröffentlichung; kann auch Webhooks abonnieren.
• approve – Freigeben: echte Planung, nur wenn der Workspace es erlaubt. Wird nie standardmäßig angefragt – nur wenn scope es nennt.

Verbindungen widerrufen

Nutzer sehen unter Verbundene Apps auf der Karte REST API, welche Apps auf ihren Workspace zugreifen; Widerrufen macht die Tokens sofort ungültig und löscht auch die Webhooks, die die App angelegt hat. Als Entwickler pausierst du mit Ausschalten bei deiner App alle Verbindungen, mit Löschen beendest du sie endgültig. Per Code widerruft der Endpunkt /api/oauth/revoke einen Token.