AdAce AdsAdAce Ads API-Schlüssel: Scopes, Ablauf, Verifizierung und Widerruf
Ein AdAce Ads API-Schlüssel authentifiziert einen unterstützten MCP-Client oder eine REST-Integration ohne interaktive Anmeldung bei jeder Anfrage. Er ist ein Zugangsdaten-Token, kein Google- oder Meta-Token. Erstellen Sie ihn nur für eine bestimmte Integration und einen bestimmten Arbeitsbereich, beginnen Sie mit dem Mindest-Scope und prüfen Sie, was die Integration tatsächlich lesen kann.
Was ein Schlüssel autorisiert
Ein Schlüssel ist an seinen Arbeitsbereich und Benutzer gebunden. Seine effektiven Berechtigungen entsprechen der Schnittmenge aus den Scopes des Schlüssels und der aktuellen Rolle des Benutzers, wobei der Kundenzugriff durch die Anwendung geprüft wird. Eine Rollenänderung kann daher einschränken, was ein bestehender Schlüssel darf. Das Kopieren einer Arbeitsbereichs-ID in eine Anfrage gewährt keinen Zugriff auf diesen Arbeitsbereich. Nutzen Sie Lesezugriff für Berichte; ein Schlüssel kann nicht eigenständig Zugriff auf einen nicht zugewiesenen Kunden oder ein getrenntes Provider-Konto gewähren.
Der vollständige Wert ak_prefix_secret wird nur einmal bei der Erstellung zurückgegeben, während AdAce Ads einen Hash zur Verifizierung speichert. Das angezeigte Präfix identifiziert einen Schlüssel, ohne seinen vollständigen Wert preiszugeben. Speichern Sie den vollständigen Schlüssel in der freigegebenen Secret-Konfiguration der empfangenden Integration. Fügen Sie ihn nicht in eine normale KI-Nachricht, URL, Quellcode, Screenshots oder Fehlerprotokolle ein. Ein fehlender gespeicherter Wert kann nicht aus dem Präfix wiederhergestellt werden: Erstellen Sie einen Ersatz und widerrufen Sie den verlorenen Schlüssel.
Über REST erlauben Schlüssel Lesezugriffe und mit dem Scope „propose“ das Erstellen von Änderungsvorschlägen; sie erlauben nicht direkt Freigaben, Ausführungen oder Änderungen an Einstellungen. Ein Vorschlag ist jedoch nicht per se wirkungslos: Eine konfigurierte Auto-Policy eines Kunden kann einen berechtigten Vorschlag innerhalb der geltenden Berechtigungen und Limits weiterleiten. MCP wendet ebenfalls Scope- und Rollenprüfungen auf die verfügbaren Tools an. Verwenden Sie Lesezugriff für Testberichte, statt anzunehmen, dass „propose“ eine manuelle Prüfung jeder nachfolgenden Aktion garantiert.
Erstellen Sie beispielsweise einen Lese-Schlüssel namens „North Store weekly report“ mit einem Ablaufdatum, das zum Prüfungszeitraum passt. Konfigurieren Sie den unterstützten Client so, dass er ihn als Authorization-Bearer-Token an den dokumentierten Endpunkt sendet. Rufen Sie get_started über MCP auf und lesen Sie anschließend die Kontoliste des freigegebenen Kunden aus. Vergleichen Sie ein bekanntes Werbekonto mit der Anwendung. Dies bestätigt einen funktionierenden Lesepfad, ohne Vorschläge zu erstellen oder Werbeanzeigen zu ändern.
Zugangsdaten mit klarem Inhaber und Zweck
- Geben Sie jeder vertrauenswürdigen Integration eigene Zugangsdaten mit klarem Namen, damit Zuständigkeit und Zweck bei späteren Zugriffsprüfungen nachvollziehbar bleiben.
- Beschränken Sie den Zugriff über Scopes, aktuelle Benutzerberechtigungen und die Bindung an den Arbeitsbereich, anstatt Agenturpasswörter oder Provider-Tokens zu teilen.
- Ersetzen Sie die Zugangsdaten einer Integration bei Bedarf und verifizieren Sie den Ersatz, bevor Sie die veralteten Zugangsdaten bei der regulären Rotation entfernen.
Erstellen, verifizieren und rotieren
- Öffnen Sie „Connect AI“ → „API-Schlüssel“ im gewünschten Arbeitsbereich. Prüfen Sie die vorhandenen Namen, die Anzahl aktiver Schlüssel und die Zeitstempel der letzten Nutzung, bevor Sie neue Zugangsdaten erstellen.
- Erstellen Sie für die erste Verifizierung einen benannten Schlüssel mit Lesezugriff. Wählen Sie gegebenenfalls ein Ablaufdatum und führen Sie die von der Anwendung geforderte Zwei-Faktor-Authentifizierung durch.
- Speichern Sie den einmalig angezeigten Wert direkt in der Secret-Konfiguration der vertrauenswürdigen Integration. Behalten Sie nur Namen, Präfix, Inhaber, Verwendungszweck und Ablaufdatum in Ihrer Zugriffsübersicht.
- Führen Sie über die Integration einen zulässigen Leseaufruf durch. Überprüfen Sie sowohl die zurückgegebenen Daten als auch die Aktivitäts- oder Nutzungsnachweise; der Zeitstempel der letzten Nutzung wird höchstens einmal pro Minute aktualisiert.
- Für eine reguläre Rotation erstellen und verifizieren Sie den Ersatz, stellen die Integration um und widerrufen den alten Schlüssel. Wurde ein Schlüssel kompromittiert, widerrufen Sie ihn unverzüglich und prüfen Sie dessen Aktivitäten, bevor Sie einen Ersatz einrichten.
Limits, Fehler und kompromittierte Zugangsdaten
- Erstellungslimit: Die Implementierung erlaubt fünf aktive Schlüssel pro Person in einem Arbeitsbereich. Abgelaufene oder widerrufene Schlüssel belegen keinen aktiven Platz mehr. Bereinigen Sie veraltete Integrationen, statt Schlüssel zu teilen, um das Limit zu umgehen.
- 401 oder abgelehnte Zugangsdaten: Prüfen Sie Endpunkt, Bearer-Header, vollständigen Wert, Ablauf und Widerruf. 403: Prüfen Sie Arbeitsbereich, effektiven Scope, aktuelle Rolle und Kundenzuweisung. Ein Lese-Schlüssel sollte nicht erweitert werden, nur weil eine Einstellungs- oder Vorschlagsanfrage abgelehnt wurde.
- Eine Rate-Limit-Antwort erfordert das Warten gemäß Retry-After und das Reduzieren wiederholter Aufrufe; sie bedeutet nicht, dass der Schlüssel widerrufen wurde. Ein Schlüsselwiderruf blockiert nachfolgende Authentifizierungen, löscht jedoch keine früheren Berichte und macht keine Änderungen rückgängig. Lokale Tests verifizieren Implementierungsregeln, nicht die Freigabe der Produktionsintegration oder die öffentliche Verfügbarkeit.
Quellen und weiterführende Literatur
Testen Sie es mit Ihren eigenen Konten
Erstellen Sie einen Arbeitsbereich, verbinden Sie Google oder Meta mit wenigen Klicks und behalten Sie den klaren Überblick über Ihre Konten. Änderungen erfolgen nur nach Ihrer Freigabe oder nach Ihren festgelegten Richtlinien.
Arbeitsbereich erstellen