Przewodnik OAuth

Wszystkie wywołania API wymagają autoryzacji i są wykonywane w imieniu autoryzowanego użytkownika Ahrefs. Aby to zrobić, Twoja aplikacja musi uzyskać dla tego użytkownika token dostępu API.

Ahrefs Connect korzysta z OAuth 2.0 Authorization Code Flow z Proof Key for Code Exchange (PKCE). Proces składa się z dwóch głównych kroków:

1. Autoryzuj aplikację

Przekieruj użytkownika do:

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}

Parametry:

• {client_id} : Zakodowany w URL identyfikator klienta (Client ID) z sekcji Ahrefs Connect w Ustawieniach konta.
• {redirect_uri} : Zakodowany w URL Redirect URI zarejestrowany w tej samej sekcji.
• {code_challenge} : Wyprowadzony z weryfikatora kodu (code verifier) przy użyciu metody S256:
  • Wygeneruj weryfikator kodu (code verifier) — losowy ciąg 43–128 znaków, korzystając z kryptograficznie bezpiecznego generatora. Dozwolone znaki: [A-Z] [a-z] [0-9] - . _ ~ (zob. RFC7636, sekcja 4.1).
  • Oblicz skrót SHA-256 weryfikatora kodu.
  • Zakoduj skrót w Base64-URL.
  • Użyj tej zakodowanej wartości jako code_challenge (zob. RFC7636, sekcja 4.2).
• {state} : Wygeneruj nieprzezroczystą (opaque) wartość, aby zachować stan między żądaniem a wywołaniem zwrotnym. Serwer autoryzacji dołączy tę wartość podczas przekierowywania użytkownika z powrotem do Twojej aplikacji. (zob. RFC6749, sekcja 4.1.1)

Doświadczenie użytkownika:

1. Użytkownik widzi ekran zgody na autoryzację Ahrefs.
2. Udziela Twojej aplikacji uprawnienia do dostępu do Ahrefs API w swoim imieniu.
3. Ahrefs przekierowuje go do Twojego Redirect URI z:
   • parametrem code — używanym w kroku 2
   • parametrem state — sprawdź, czy jest zgodny z Twoim pierwotnym żądaniem.

2. Pobierz access_token

Wymień code na access_token, wysyłając żądanie POST do https://ahrefs.com/oauth/token .

Wyślij parametry w treści żądania w formacie application/x-www-form-urlencoded (zob. RFC6749 sekcja 4.1.3):

• grant_type: authorization_code
• client_id: {client_id} (Musi być zgodny z tym z kroku 1)
• redirect_uri: {redirect_uri} (Musi być zgodny z tym z kroku 1)
• code: {code} (Z kroku 1)
• code_verifier: {original_code_verifier} (Nieprzekształcona wartość z kroku 1)
• client_secret: {client_secret} (Tylko aplikacje webowe — znajduje się w sekcji Ahrefs Connect w Ustawieniach konta. Pomiń w przypadku aplikacji desktopowych.)

Przykładowa odpowiedź:

{
    "access_token": "\<token do użycia w zapytaniach API>",
    "expires_in": \<czas życia tokenu dostępu w sekundach>,
    "token_type": "Bearer",
    "scope": "apiv3-integration-apps"
}

Okres ważności Tokena i ponowne połączenie

• Nie są wydawane Tokeny odświeżania.
• Tokeny dostępu są ważne przez 1 rok. Po wygaśnięciu użytkownik musi ponownie się połączyć (ponownie autoryzować) przez OAuth.