OAuthガイド

すべてのAPI呼び出しには認可が必要で、認可されたAhrefsユーザーの代理として実行されます。 そのために、アプリはそのユーザー用のAPI アクセストークンを取得する必要があります。

Ahrefs Connectは、PKCE（Proof Key for Code Exchange）付きOAuth 2.0 認可コードフローを使用します。 このプロセスには、主に2つのステップがあります:

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エンコード済みのクライアントID。
• {redirect_uri} : 同じセクションで登録した、URLエンコード済みのリダイレクトURI。
• {code_challenge} : S256方式を使用してコード検証子（code verifier）から導出した値:
  • コード検証子（code verifier）を生成します。暗号学的に安全なジェネレーターを使用し、43〜128文字のランダムな文字列にします。 使用可能な文字: [A-Z] [a-z] [0-9] - . _ ~（RFC7636 セクション4.1参照）。
  • コード検証子のSHA-256ハッシュを計算します。
  • ハッシュをBase64 URLセーフエンコードします。
  • このエンコードした値をcode_challengeとして使用します（RFC7636 セクション4.2参照）。
• {state} : リクエストとコールバック間の状態を維持するために、推測困難な不透明な値を生成します。 認可サーバーは、ユーザーをアプリにリダイレクトして戻す際に、この値を含めます。 （RFC6749 セクション4.1.1参照）

ユーザー体験:

1. ユーザーには Ahrefs の認可（承認）画面が表示されます。
2. ユーザーはアプリに対して、自分に代わって Ahrefs API へアクセスする権限を許可します。
3. Ahrefs は以下を付与して、ユーザーを リダイレクト URI にリダイレクトします：
   • code パラメータ — 手順 2 で使用します
   • state パラメータ — 元のリクエストと一致することを検証します。

2. access_token を取得する

https://ahrefs.com/oauth/token に POST リクエストを送信して、code を access_token に交換します。

リクエスト本文には application/x-www-form-urlencoded 形式で パラメータを送信 します（RFC6749 Section 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}（Web アプリのみ — アカウント設定の Ahrefs Connect セクションにあります。 デスクトップアプリの場合は省略します。）

レスポンス例:

{
    "access_token": "\<API リクエストで使用するトークン>",
    "expires_in": \<アクセストークンの有効期間（秒）>,
    "token_type": "Bearer",
    "scope": "apiv3-integration-apps"
}

トークンの有効期間と再接続

• リフレッシュトークンは発行されません。
• アクセストークンの有効期間は1年です。 有効期限が切れた後は、ユーザーはOAuth経由で**再接続（再認可）**する必要があります。