OAuth 가이드

모든 API 호출은 권한 부여가 필요하며, 권한이 부여된 Ahrefs 사용자를 대신해 수행됩니다. 이를 위해 앱은 해당 사용자의 API 액세스 토큰을 획득해야 합니다.

Ahrefs Connect는 PKCE(Proof Key for Code Exchange)를 사용한 OAuth 2.0 인가 코드 플로우를 사용합니다. 이 과정은 크게 두 단계로 구성됩니다:

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} : 계정 설정의 Ahrefs Connect 섹션에서 확인할 수 있는 URL 인코딩된 Client ID입니다.
• {redirect_uri} : 같은 섹션에 등록한 URL 인코딩된 Redirect URI입니다.
• {code_challenge} : S256 메서드를 사용해 code verifier에서 파생한 값입니다:
  • 암호학적으로 안전한 생성기를 사용해 43~128자 길이의 무작위 문자열인 code verifier를 생성합니다. 허용 문자: [A-Z] [a-z] [0-9] - . _ ~(자세한 내용은 RFC7636 4.1절 참고).
  • code verifier의 SHA-256 해시를 계산합니다.
  • 해시를 Base64 URL 안전 방식으로 인코딩합니다.
  • 이 인코딩된 값을 code_challenge로 사용합니다(RFC7636 4.2절 참고).
• {state} : 요청과 콜백 간의 상태를 유지하기 위한 불투명한 값을 생성합니다. 인가 서버는 사용자를 앱으로 다시 리디렉션할 때 이 값을 포함합니다. (RFC6749 4.1.1절 참고)

사용자 경험:

1. 사용자는 Ahrefs 권한 부여 동의 화면을 보게 됩니다.
2. 사용자는 자신을 대신해 Ahrefs API에 접근할 수 있도록 앱에 권한을 부여합니다.
3. Ahrefs가 다음 정보를 포함해 사용자를 Redirect URI로 리디렉션합니다:
   • code 매개변수 — 2단계에서 사용
   • state 매개변수 — 원래 요청과 일치하는지 확인

2. access_token 가져오기

https://ahrefs.com/oauth/token에 POST 요청을 보내 code를 access_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": \<액세스 토큰의 유효 기간(초)>,
    "token_type": "Bearer",
    "scope": "apiv3-integration-apps"
}

토큰 수명 및 재연결

• 리프레시 토큰은 발급되지 않습니다.
• 액세스 토큰은 1년 동안 유효합니다. 만료 후에는 OAuth를 통해 다시 연결(재승인) 해야 합니다.