Authentifizierung

Verwenden Sie einen API-Schlüssel für Ihr eigenes Backend oder für Automatisierungen. Verwenden Sie OAuth, wenn Ihre Anwendung andere Make Agent Fast-Nutzer um Zugriff bittet. Beide Arten von Zugangsdaten rufen dieselben /api/v1-Ressourcen auf und unterliegen denselben Scopes, Tarifberechtigungen, Mandantentrennungen und Ratenbegrenzungen.

API-Schlüssel#

Zum Erstellen und Verwenden eines öffentlichen API-Schlüssels ist ein aktiver kostenpflichtiger Tarif erforderlich.

1. Öffnen Sie Dashboard → Einstellungen → Entwickler.
2. Geben Sie einen Namen ein, der den Dienst und die Umgebung identifiziert, zum Beispiel Production lead export.
3. Wählen Sie die minimalen Scopes aus, die der Dienst benötigt.
4. Wählen Sie eine Gültigkeitsdauer: 30 Tage, 90 Tage, ein Jahr oder unbegrenzt.
5. Erstellen Sie den Schlüssel und kopieren Sie den Wert maf_live_... sofort.

Make Agent Fast speichert einen SHA-256-Hash statt eines wiederherstellbaren Klartexts. Das Dashboard zeigt später ein sicheres Präfix, die Scopes, das Ablaufdatum, den Zeitpunkt der letzten Verwendung und den Sperrstatus an.

Authorization: Bearer maf_live_...

Senden Sie den Header aus Servercode:

curl --fail-with-body https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

Fehlende Zugangsdaten liefern 401 authentication_required. Ungültige, abgelaufene oder widerrufene Schlüssel liefern 401 invalid_api_key. Ein Schlüssel, dessen Konto keinen aktiven kostenpflichtigen Tarif mehr hat, liefert 403 subscription_required.

Schlüssel rotieren oder widerrufen#

Erstellen Sie einen Ersatz, bevor Sie den alten Schlüssel widerrufen. Stellen Sie den Ersatzschlüssel bereit, senden Sie eine echte Anfrage, prüfen Sie deren x-request-id und klicken Sie dann beim alten Schlüssel auf Widerrufen. Der Widerruf wirkt sofort und kann nicht rückgängig gemacht werden.

In den Entwickler-Einstellungen können Sie mit Bearbeiten den Namen und die Scopes eines aktiven Schlüssels ändern; die Änderung gilt sofort für denselben Schlüssel. Das Ablaufdatum und das Token lassen sich nicht ändern – erstellen Sie für ein neues Ablaufdatum oder ein rotiertes Token einen Ersatzschlüssel.

OAuth-Anwendungen#

OAuth ist für Software gedacht, die Konten verbindet, die anderen Make Agent Fast-Nutzern gehören. Es verwendet den Autorisierungscode-Flow mit PKCE (S256) und gibt kein Client Secret aus und benötigt auch keines. Die Client-ID ist öffentlich; Autorisierungscodes, Access Tokens, Refresh Tokens und der PKCE-Verifier sind vertraulich.

1. Anwendung registrieren#

Öffnen Sie Dashboard → Einstellungen → Entwickler → OAuth-Anwendungen. Fügen Sie Folgendes hinzu:

• Einen Anwendungsnamen mit 2 bis 100 Zeichen.
• Zwischen 1 und 10 exakte Redirect-URLs.
• Die maximalen Scopes, die Ihre Anwendung anfordern darf.

Redirect-URLs in der Produktion müssen HTTPS verwenden und dürfen weder Zugangsdaten noch Fragmente enthalten. Der vollständige URI muss bei der Autorisierung und beim Token-Austausch mit einem registrierten Wert übereinstimmen. Neu eingereichte Anwendungen haben den Status pending; die Autorisierung funktioniert erst, nachdem die Anwendung geprüft und als approved markiert wurde.

Der Plattformbetreiber prüft ausstehende Client-IDs mit dem protokollierten oauth:review-Workflow. Bewahren Sie die nach dem Einreichen angezeigte Client-ID auf; ihr Status ist auf der Seite „Entwickler“ sichtbar, und bei abgelehnten Anwendungen wird die Entscheidung der Prüfung angezeigt, bevor sie erneut eingereicht werden können.

2. PKCE-Werte generieren#

Generieren Sie für jeden Autorisierungsversuch einen neuen Verifier und bewahren Sie ihn zusammen mit state in derselben geschützten, kurzlebigen Sitzung auf.

import { createHash, randomBytes } from "node:crypto";

const verifier = randomBytes(48).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");
const state = randomBytes(24).toString("base64url");

Der Verifier muss 43–128 URL-sichere PKCE-Zeichen enthalten. Es wird ausschließlich code_challenge_method=S256 akzeptiert.

3. Nutzer zur Zustimmung weiterleiten#

https://makeagent.fast/oauth/authorize
  ?client_id=maf_app_...
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &response_type=code
  &scope=sites%3Aread%20leads%3Aread
  &state=RANDOM_STATE
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256

Der Nutzer meldet sich an, prüft die angeforderten Scopes und erlaubt oder verweigert den Zugriff. Bei Erfolg leitet Make Agent Fast mit code und dem ursprünglichen state auf den exakten registrierten URI weiter. Bei Ablehnung wird error=access_denied gesendet, zusammen mit dem ursprünglichen state, sofern einer übergeben wurde.

Lehnen Sie den Callback ab, wenn state nicht exakt mit dem für diese Browsersitzung gespeicherten Wert übereinstimmt.

4. Autorisierungscode austauschen#

Der Autorisierungscode läuft nach 10 Minuten ab und kann nur einmal verwendet werden.

curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "code=$AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=https://app.example.com/oauth/callback" \
  --data-urlencode "code_verifier=$PKCE_VERIFIER"

{
  "access_token": "maf_live_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "maf_refresh_...",
  "scope": "sites:read leads:read"
}

Das Access Token ist eine Stunde gültig. Das Refresh Token ist bis zu 90 Tage gültig, sofern es nicht vorher rotiert oder widerrufen wird.

5. Refresh Token rotieren#

Jede erfolgreiche Aktualisierung widerruft sowohl das übermittelte Refresh Token als auch das zugehörige vorherige Access Token und gibt ein neues Paar zurück. Speichern Sie das neue Paar atomar, bevor Sie den Zustand der vorherigen Antwort verwerfen.

curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"

Die erneute Verwendung eines Autorisierungscodes oder eines rotierten Refresh Tokens liefert invalid_grant. Der OAuth-Token-Endpunkt gibt Antworten im OAuth-Stil { "error", "error_description" } zurück statt des öffentlichen API-Fehlerformats und erlaubt 30 Token-Anfragen pro Aufrufer-IP-Adresse und Minute.

Verwenden Sie niemals Management-Anfragen im Browsercode zur Authentifizierung#

Legen Sie keinen geheimen API-Schlüssel, kein Access Token und kein Refresh Token in React-Client-Komponenten, statischem JavaScript, mobilem Web, Webflow, Framer, Wix oder Shopify Liquid ab. Verwenden Sie Ihr authentifiziertes Backend. Die öffentliche Website-Einbettung verwendet einen nicht geheimen Site-Slug und eine Origin-Allowlist, keine Zugangsdaten der Management-API.

Siehe Zugangsdaten und Tokens, Scopes und Fehler und API-Schnellstart.