Amazon Ads Refresh Tokens: 365-Tage-Frist und zuverlässige Ablaufüberwachung

Amazon Ads Refresh Tokens: 365-Tage-Frist und zuverlässige Ablaufüberwachung

Seit dem 30. Juli 2026 gilt für neu ausgestellte Refresh Tokens der Amazon-Ads-Werbeberechtigungen eine feste Laufzeit: 365 Tage ab Einwilligung des Advertisers. Der Tausch gegen neue Access Tokens startet diese Frist nicht erneut. Ein lokales Register ermöglicht Vorwarnungen; ergänzendes Fehlermonitoring erkennt widerrufene oder anderweitig ungültige Zugangsdaten auch vor dem geplanten Termin.

Ein Access Token authentifiziert API-Anfragen und gilt normalerweise 60 Minuten. Ein Refresh Token beschafft neue Access Tokens, ohne bei jedem Tausch erneut den Einwilligungsdialog durchlaufen zu müssen.

1. Für welche Tokens die 365-Tage-Regel gilt

Amazon wendet die Regel auf ab dem 30. Juli 2026 ausgestellte Tokens für advertising::campaign_management und advertising::audiences an. Frühere Tokens erhalten durch diese Änderung kein festes Ablaufdatum, bleiben aber widerrufbar und können aus anderen Gründen ungültig werden. Entscheidend ist die Token-Ausstellung, nicht allein der Aufnahmezeitpunkt eines Werbekontos in eine Integration.

Die feste Laufzeit beginnt mit der Einwilligung. Ein Refresh-Tausch liefert ein neues Access Token und dasselbe Refresh Token; eine neue Einwilligung ist ein anderer Vorgang. OAuth-Anbieter verwenden unterschiedliche Regeln. Eine gleitende Laufzeit ist deshalb keine allgemeine Eigenschaft von Refresh Tokens. Außerdem sind die Amazon-Ads-Regeln von den Autorisierungsregeln der Selling Partner API zu unterscheiden.

Der aktuelle Amazon-Ads-Leitfaden empfiehlt vorausschauende Altersüberwachung und erneute Autorisierung. Eine pauschale Aussage, Amazon verschicke niemals E-Mails, Konsolenhinweise oder andere Erinnerungen, ist durch diesen Leitfaden nicht belegt. Die betriebliche Überwachung sollte unabhängig von einer angenommenen Anbieterbenachrichtigung funktionieren.

2. Ein Register für Autorisierungen statt Token-Inhalte

Das PostgreSQL-Beispiel speichert eine Zeile je unabhängig verwalteter Autorisierung. authorization_id ist eine interne stabile Kennung; client_id bezeichnet die Anwendung. Mehrere Anwendungen oder Berechtigungen für denselben Advertiser benötigen getrennte Zeilen. Ein Kontoname allein ist keine eindeutige Autorisierungskennung. Echte Refresh Tokens und Client Secrets gehören in geschützte Geheimnisverwaltung, außerhalb dieser Tabelle und der Alarmausgabe.

Das Feld policy unterscheidet fixed_365, legacy und unknown. Legacy-Zeilen erhalten kein berechnetes Ablaufdatum. Fehlende Belege gehören unter unknown und lösen eine Meldung aus, statt ein erfundenes Einwilligungsdatum zu erzeugen. Für fixed_365 enthält consent_date das UTC-Kalenderdatum der protokollierten Einwilligung und token_issued_at den tatsächlichen Ausstellungszeitpunkt. Für die Einordnung rund um den Stichtag ist ein verlässliches Autorisierungsprotokoll erforderlich.

CREATE TABLE amazon_ads_token_ledger (
    authorization_id text PRIMARY KEY,
    client_id        text NOT NULL,
    account_name     text NOT NULL,
    policy           text NOT NULL
                     CHECK (policy IN ('fixed_365', 'legacy', 'unknown')),
    consent_date     date,
    token_issued_at  timestamptz,
    expires_on       date GENERATED ALWAYS AS (
        CASE WHEN policy = 'fixed_365' THEN consent_date + 365 END
    ) STORED,
    last_refresh_ok  timestamptz,
    owner_email      text NOT NULL,
    status           text NOT NULL DEFAULT 'active'
                     CHECK (status IN ('active', 'revoked')),
    CHECK (policy <> 'fixed_365' OR
           (consent_date IS NOT NULL AND token_issued_at IS NOT NULL)),
    CHECK (policy <> 'fixed_365' OR
           (token_issued_at AT TIME ZONE 'UTC')::date >= DATE '2026-07-30'),
    CHECK (policy <> 'legacy' OR
           (token_issued_at IS NOT NULL AND
            (token_issued_at AT TIME ZONE 'UTC')::date < DATE '2026-07-30'))
);

CREATE INDEX ON amazon_ads_token_ledger (expires_on)
WHERE status = 'active';

expires_on ist ein konservativer Planungstermin: Einwilligungsdatum plus 365 Tage. Ein reiner Datumswert belegt keinen sekundengenauen Ablaufzeitpunkt auf Amazons Servern. Das Prüfskript behandelt den Beginn dieses UTC-Tages als kritische Planungsgrenze; die Erneuerung gehört deshalb vor diesen Tag. Eine generierte Spalte hält die Rechnung konsistent mit den gespeicherten Eingaben. Falsche Ausgangsdaten ergeben weiterhin falsche Termine.

3. Prüfskript mit ausdrücklichen Fehlerzuständen

Dieses Python-3-Beispiel benötigt Psycopg 3. Die Datenbankrolle braucht lediglich SELECT auf das Register. Die Verbindungsangaben stammen aus ADS_LEDGER_DSN; Zugangsdaten können über eine geschützte PostgreSQL-Passwortdatei oder passende Dienstkonfiguration bereitstehen. Das Beispiel begrenzt Verbindungs- und Abfragezeit und gibt bei Fehlern weder DSN noch Token-Inhalte aus.

#!/usr/bin/env python3
import os
import sys
import psycopg

WARN_DAYS = 60
QUERY = """
SELECT authorization_id, account_name, policy, expires_on,
       expires_on - CURRENT_DATE AS days_left, owner_email
FROM amazon_ads_token_ledger
WHERE status = 'active'
  AND (policy = 'unknown' OR expires_on <= CURRENT_DATE + %s)
ORDER BY expires_on NULLS FIRST, authorization_id
"""

def render(rows):
    result = 0
    for aid, name, policy, expires, days, owner in rows:
        if policy == 'unknown':
            state = 'UNKNOWN: authorization metadata needs review'
            result = 2
        elif days <= 0:
            state = 'DUE: planning deadline reached; check authorization'
            result = max(result, 1)
        else:
            state = f'WARNING: {days} days to planning deadline'
        print(f'{aid} | {name} | {state} | deadline={expires} | owner={owner}')
    return result

def main():
    dsn = os.environ.get('ADS_LEDGER_DSN')
    if not dsn:
        print('CHECK FAILED: ADS_LEDGER_DSN is missing', file=sys.stderr)
        return 2
    try:
        with psycopg.connect(dsn, connect_timeout=5,
                options='-c timezone=UTC -c statement_timeout=5000') as conn:
            rows = conn.execute(QUERY, (WARN_DAYS,)).fetchall()
    except psycopg.Error as exc:
        # No DSN, credentials or token contents in diagnostic output.
        print(f'CHECK FAILED: {type(exc).__name__}', file=sys.stderr)
        return 2
    return render(rows)

if __name__ == '__main__':
    sys.exit(main())

Exit-Code 0 bedeutet, dass kein kritischer Zustand gefunden wurde; Vorwarnungen erzeugen trotzdem Ausgabe. Exit-Code 1 meldet einen erreichten Planungstermin. Exit-Code 2 steht für unbekannte Autorisierungsdaten oder eine fehlgeschlagene Prüfung. Ein Monitoring-Wrapper muss diese Codes tatsächlich auswerten. Die 60-Tage-Schwelle ist ein anpassbarer organisatorischer Puffer, keine Amazon-Vorgabe und keine allgemein gemessene Freigabedauer.

4. Zeitplan und Zustellung

# Service-user crontab; working local mail transport required.
MAILTO=ads-ops@example.com
ADS_LEDGER_DSN="dbname=ops user=ads_ledger_reader"
17 6 * * * /opt/ads/venv/bin/python /opt/ads/token_ledger_check.py

Pfade und Datenbankrolle sind Beispiele für die Einrichtung. Die private Python-Umgebung benötigt Psycopg, und die lokale Anmeldung muss die lesende Rolle zulassen. Cron läuft um 06:17 Uhr in der konfigurierten Zeitzone des Schedulers; die SQL-Datumsberechnung verwendet ausdrücklich UTC. MAILTO benötigt funktionierenden lokalen Mailtransport und einen geprüften Empfänger. Das Skript versendet selbst keine E-Mail. owner_email kennzeichnet lediglich die Zuständigkeit und ist keine automatische Zustelladresse.

Solange ein Zustand besteht, kann die Ausgabe täglich eine Erinnerung auslösen. Eskalation, Bestätigung und Begrenzung der Nachrichtenanzahl gehören in das umgebende Monitoring. Ein unabhängiges Lebenszeichen oder eine Kontrolle ausgebliebener Läufe ist erforderlich, weil ein gestoppter Scheduler den eigenen Ausfall nicht melden kann. last_refresh_ok ist nur dann nützlich, wenn der Refresh-Prozess das Feld aktualisiert und eine separate Aktualitätsprüfung den Wert auswertet.

5. Erneuerung und Fehlerbehandlung

Ein ungültiges Refresh Token führt laut Amazon zu HTTP 400 mit invalid_grant. Ein Reporting-Job muss diesen Fehler melden, statt gültige Berichte durch leere Daten zu ersetzen. Bei Netzwerkfehlern können begrenzte Wiederholungen sinnvoll sein; einen ungültigen Grant reparieren Wiederholungen nicht. Die Wiederherstellung benötigt einen neuen Authorization Grant über den Einwilligungsablauf. Nach erfolgreicher Erneuerung werden Geheimnis und Register konsistent aktualisiert; anschließend folgen ein echter Access-Token-Tausch und eine minimale berechtigte API-Prüfung.