Guía de OAuth

Todas las llamadas a la API requieren autorización y se realizan en nombre de un usuario de Ahrefs autorizado. Para ello, tu aplicación debe obtener un token de acceso de la API para ese usuario.

Ahrefs Connect utiliza el flujo de código de autorización de OAuth 2.0 con Proof Key for Code Exchange (PKCE). El proceso consta de dos pasos principales:

1. Autorizar la aplicación

Redirige al usuario a:

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}

Parámetros:

• {client_id} : ID de cliente codificado en URL, de la sección Ahrefs Connect en la Configuración de la cuenta.
• {redirect_uri} : URI de redirección codificada en URL que has registrado en la misma sección.
• {code_challenge} : Derivado de un code verifier mediante el método S256:
  • Genera un code verifier — una cadena aleatoria de 43–128 caracteres usando un generador criptográficamente seguro. Caracteres permitidos: [A-Z] [a-z] [0-9] - . _ ~ (consulta la Sección 4.1 de RFC7636).
  • Calcula el hash SHA-256 del code verifier.
  • Codifica el hash en Base64-URL.
  • Usa este valor codificado como code_challenge (consulta la Sección 4.2 de RFC7636).
• {state} : Genera un valor opaco para mantener el estado entre la solicitud y el callback. El servidor de autorización incluirá este valor al redirigir al usuario de vuelta a tu aplicación. (consulta la Sección 4.1.1 de RFC6749)

Experiencia del usuario:

1. El usuario ve la pantalla de consentimiento de autorización de Ahrefs.
2. Concede a tu app permiso para acceder a la API de Ahrefs en su nombre.
3. Ahrefs lo redirige a tu URI de redirección con:
   • parámetro code — se usa en el paso 2
   • parámetro state — comprueba que coincida con tu solicitud original.

2. Obtener el access_token

Intercambia el code por un access_token enviando una solicitud POST a https://ahrefs.com/oauth/token .

Envía los parámetros en el cuerpo de la solicitud con el formato application/x-www-form-urlencoded (consulta la Sección 4.1.3 de RFC6749):

• grant_type: authorization_code
• client_id: {client_id} (Debe coincidir con el del paso 1)
• redirect_uri: {redirect_uri} (Debe coincidir con el del paso 1)
• code: {code} (Del paso 1)
• code_verifier: {original_code_verifier} (El valor sin transformar del paso 1)
• client_secret: {client_secret} (Solo para apps web — se encuentra en la sección Ahrefs Connect de la Configuración de la cuenta. Omítelo para apps de escritorio.)

Respuesta de ejemplo:

{
    "access_token": "\<token para usar en las solicitudes a la API>",
    "expires_in": \<vida útil del access token en segundos>,
    "token_type": "Bearer",
    "scope": "apiv3-integration-apps"
}

Duración del token y reconexión

• No se emiten tokens de actualización.
• Los tokens de acceso son válidos durante 1 año. Tras la expiración, el usuario debe volver a conectarse (volver a autorizar) a través de OAuth.