OAuth 指南

所有 API 调用都需要授权，并且是以已授权的 Ahrefs 用户身份发起的。 为此，你的应用必须为该用户获取一个 API 访问令牌。

Ahrefs Connect 使用 OAuth 2.0 授权码流程（Authorization Code Flow）并结合代码交换的证明密钥（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}：在你的 Account settings 中 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 节）。
  • 计算 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}（仅适用于 Web 应用——可在 账户设置 的 Ahrefs Connect 部分找到。 桌面应用请省略。）

响应示例：

{
    "access_token": "\<用于 API 请求的令牌>",
    "expires_in": \<访问令牌的有效期（秒）>,
    "token_type": "Bearer",
    "scope": "apiv3-integration-apps"
}

令牌有效期与重新连接

• 不发放刷新令牌。
• 访问令牌有效期为 1 年。 到期后，用户必须通过 OAuth 重新连接（重新授权）。