Посібник з OAuth

Усі виклики API потребують авторизації та виконуються від імені авторизованого користувача Ahrefs. Для цього ваш застосунок має отримати токен доступу API для цього користувача.

Ahrefs Connect використовує OAuth 2.0 Authorization Code Flow з Proof Key for Code Exchange (PKCE). Процес складається з двох основних кроків:

1. Авторизуйте застосунок

Перенаправте користувача на:

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}

Параметри:

• {client_id} : URL-encoded Client ID з розділу Ahrefs Connect у ваших налаштуваннях облікового запису.
• {redirect_uri} : URL-encoded Redirect URI, який ви зареєстрували в тому самому розділі.
• {code_challenge} : Отримується з code verifier за допомогою методу S256:
  • Згенеруйте code verifier — випадковий рядок довжиною 43–128 символів за допомогою криптографічно безпечного генератора. Дозволені символи: [A-Z] [a-z] [0-9] - . _ ~ (див. RFC7636 Section 4.1).
  • Обчисліть хеш SHA-256 для code verifier.
  • Закодуйте хеш у форматі Base64-URL.
  • Використайте це закодоване значення як code_challenge (див. RFC7636 Section 4.2).
• {state} : Згенеруйте непрозоре значення, щоб зберегти стан між запитом і зворотним викликом. Сервер авторизації додасть це значення під час перенаправлення користувача назад у ваш застосунок. (див. RFC6749 Section 4.1.1)

Досвід користувача:

1. Користувач бачить екран згоди на авторизацію Ahrefs.
2. Вони надають вашому застосунку дозвіл на доступ до Ahrefs API від свого імені.
3. Ahrefs перенаправляє їх на ваш Redirect URI з:
   • параметром code — використовується на кроці 2
   • параметром state — перевірте, що він збігається з вашим початковим запитом.

2. Отримайте access_token

Обміняйте code на access_token, надіславши запит POST на https://ahrefs.com/oauth/token .

Передайте параметри в тілі запиту у форматі application/x-www-form-urlencoded (див. RFC6749, розділ 4.1.3):

• grant_type: authorization_code
• client_id: {client_id} (має збігатися з тим, що вказано на кроці 1)
• redirect_uri: {redirect_uri} (має збігатися з тим, що вказано на кроці 1)
• code: {code} (з кроку 1)
• code_verifier: {original_code_verifier} (значення з кроку 1 без перетворень)
• client_secret: {client_secret} (лише для вебзастосунків — знаходиться в розділі Ahrefs Connect у налаштуваннях акаунта). Для десктопних застосунків не вказуйте.)

Приклад відповіді:

{
    "access_token": "\<токен для використання в API-запитах>",
    "expires_in": \<час дії access_token у секундах>,
    "token_type": "Bearer",
    "scope": "apiv3-integration-apps"
}

Термін дії токена та повторне підключення

• Refresh токен не видається.
• Access токен дійсний протягом 1 року. Після завершення терміну дії користувач має підключитися знову (повторно авторизуватися) через OAuth.