OAuth-Leitfaden

Alle API-Aufrufe erfordern eine Autorisierung und werden im Namen eines autorisierten Ahrefs-Nutzers ausgeführt. Dafür muss Ihre App für diesen Nutzer ein API-Zugriffstoken erhalten.

Ahrefs Connect verwendet den OAuth 2.0 Authorization Code Flow mit Proof Key for Code Exchange (PKCE). Der Prozess besteht aus zwei Hauptschritten:

1. Anwendung autorisieren

Leiten Sie den Nutzer weiter zu:

https://app.ahrefs.com/web/oauth/authorize?response_type=code&client_id={client_id}&scope=apiv3-integration-apps&redirect_uri={redirect_uri}&code_challenge={code_challenge}&code_challenge_method=s256&state={state}

Parameter:

• {client_id} : URL-codierte Client-ID aus dem Bereich Ahrefs Connect in Ihren Kontoeinstellungen.
• {redirect_uri} : URL-codierte Redirect-URI, die Sie im selben Bereich registriert haben.
• {code_challenge} : Abgeleitet aus einem Code Verifier mithilfe der S256-Methode:
  • Generieren Sie einen Code Verifier — eine zufällige Zeichenfolge mit 43–128 Zeichen mit einem kryptografisch sicheren Generator. Zulässige Zeichen: [A-Z] [a-z] [0-9] - . _ ~ (siehe RFC7636 Abschnitt 4.1).
  • Berechnen Sie den SHA-256-Hash des Code Verifier.
  • Kodieren Sie den Hash mit Base64-URL.
  • Verwenden Sie diesen kodierten Wert als code_challenge (siehe RFC7636 Abschnitt 4.2).
• {state} : Generieren Sie einen opaken Wert, um den Zustand zwischen der Anfrage und dem Callback beizubehalten. Der Autorisierungsserver wird diesen Wert beim Zurückleiten des Nutzers zu Ihrer App mitgeben. (siehe RFC6749 Abschnitt 4.1.1)

Nutzererlebnis:

1. Der Nutzer sieht den Ahrefs-Autorisierungs-Zustimmungsbildschirm.
2. Er erteilt Ihrer App die Berechtigung, in seinem Namen auf die Ahrefs API zuzugreifen.
3. Ahrefs leitet ihn zu Ihrer Redirect URI weiter – mit:
   • code-Parameter — wird in Schritt 2 verwendet
   • state-Parameter — prüfen Sie, ob er mit Ihrer ursprünglichen Anfrage übereinstimmt.

2. Rufen Sie das access_token ab

Tauschen Sie den code gegen ein access_token aus, indem Sie eine POST-Anfrage an https://ahrefs.com/oauth/token senden.

Senden Sie die Parameter im Request-Body im Format application/x-www-form-urlencoded (siehe RFC6749 Abschnitt 4.1.3):

• grant_type: authorization_code
• client_id: {client_id} (Muss mit dem Wert in Schritt 1 übereinstimmen)
• redirect_uri: {redirect_uri} (Muss mit dem Wert in Schritt 1 übereinstimmen)
• code: {code} (Aus Schritt 1)
• code_verifier: {original_code_verifier} (Der nicht transformierte Wert aus Schritt 1)
• client_secret: {client_secret} (Nur Web-Apps — zu finden im Bereich Ahrefs Connect in den Kontoeinstellungen. Bei Desktop-Apps weglassen.)

Beispielantwort:

{
    "access_token": "\<Token zur Verwendung in API-Anfragen>",
    "expires_in": \<Lebensdauer des Access-Tokens in Sekunden>,
    "token_type": "Bearer",
    "scope": "apiv3-integration-apps"
}

Token-Lebensdauer & erneute Verbindung

• Es werden keine Refresh-Token ausgegeben.
• Access-Token sind 1 Jahr lang gültig. Nach Ablauf muss der Nutzer sich über OAuth erneut verbinden (neu autorisieren).