Guide OAuth

Tous les appels d’API nécessitent une autorisation et sont effectués au nom d’un utilisateur Ahrefs autorisé. Pour cela, votre application doit obtenir un jeton d’accès à l’API pour cet utilisateur.

Ahrefs Connect utilise le flux OAuth 2.0 Authorization Code avec Proof Key for Code Exchange (PKCE). Le processus se déroule en deux étapes principales :

1. Autoriser l’application

Redirigez l’utilisateur vers :

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}

Paramètres :

• {client_id} : identifiant client (Client ID) encodé en URL depuis la section Ahrefs Connect dans vos Paramètres du compte.
• {redirect_uri} : URI de redirection (Redirect URI) encodée en URL que vous avez enregistrée dans la même section.
• {code_challenge} : dérivé d’un code verifier à l’aide de la méthode S256 :
  • Générez un code verifier — une chaîne aléatoire de 43 à 128 caractères à l’aide d’un générateur cryptographiquement sûr. Caractères autorisés : [A-Z] [a-z] [0-9] - . _ ~ (voir la section 4.1 de la RFC7636).
  • Calculez le hachage SHA-256 du code verifier.
  • Encodez le hachage en Base64 URL-safe.
  • Utilisez cette valeur encodée comme code_challenge (voir la section 4.2 de la RFC7636).
• {state} : générez une valeur opaque afin de maintenir l’état entre la requête et le rappel. Le serveur d’autorisation inclura cette valeur lorsqu’il redirigera l’utilisateur vers votre application. (voir la section 4.1.1 de la RFC6749)

Expérience utilisateur :

1. L’utilisateur voit l’écran de consentement d’autorisation d’Ahrefs.
2. Il autorise votre application à accéder à l’API Ahrefs en son nom.
3. Ahrefs le redirige vers votre Redirect URI avec :
   • paramètre code — utilisé à l’étape 2
   • paramètre state — vérifiez qu’il correspond à votre requête initiale.

2. Récupérer l’access_token

Échangez le code contre un access_token en envoyant une requête POST à https://ahrefs.com/oauth/token .

Envoyez les paramètres dans le corps de la requête au format application/x-www-form-urlencoded (voir la RFC6749, section 4.1.3) :

• grant_type: authorization_code
• client_id: {client_id} (doit correspondre à celui de l’étape 1)
• redirect_uri: {redirect_uri} (doit correspondre à celui de l’étape 1)
• code: {code} (de l’étape 1)
• code_verifier: {original_code_verifier} (la valeur non transformée de l’étape 1)
• client_secret: {client_secret} (Applications Web uniquement — disponible dans la section Ahrefs Connect de vos Paramètres du compte. À omettre pour les applications de bureau.)

Exemple de réponse :

{
    "access_token": "\<jeton à utiliser dans les requêtes API>",
    "expires_in": \<durée de vie du jeton d'accès en secondes>,
    "token_type": "Bearer",
    "scope": "apiv3-integration-apps"
}

Durée de vie du jeton et reconnexion

• Aucun jeton d’actualisation n’est émis.
• Les jetons d’accès sont valides pendant 1 an. Après expiration, l’utilisateur doit se reconnecter (réautoriser) via OAuth.