Guida OAuth

Tutte le chiamate API richiedono l'autorizzazione e vengono effettuate per conto di un utente Ahrefs autorizzato. Per farlo, la tua app deve ottenere un token di accesso API per quell'utente.

Ahrefs Connect utilizza il flusso del codice di autorizzazione OAuth 2.0 con Proof Key for Code Exchange (PKCE). Il processo prevede due passaggi principali:

1. Autorizzare l'applicazione

Reindirizzare l'utente 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}

Parametri:

• {client_id} : Client ID con codifica URL dalla sezione Ahrefs Connect nelle tue Impostazioni account.
• {redirect_uri} : Redirect URI con codifica URL che hai registrato nella stessa sezione.
• {code_challenge} : Derivato da un code verifier tramite il metodo S256:
  • Genera un code verifier — una stringa casuale di 43–128 caratteri generata con un generatore crittograficamente sicuro. Caratteri consentiti: [A-Z] [a-z] [0-9] - . _ ~ (vedi RFC7636 Section 4.1).
  • Calcola l'hash SHA-256 del code verifier.
  • Codifica l'hash in Base64-URL.
  • Usa questo valore codificato come code_challenge (vedi RFC7636 Section 4.2).
• {state} : Genera un valore opaco per mantenere lo stato tra la richiesta e la callback. Il server di autorizzazione includerà questo valore quando reindirizza l'utente alla tua app. (vedi RFC6749 Section 4.1.1)

Esperienza utente:

1. L’utente vede la schermata di consenso per l’autorizzazione di Ahrefs.
2. Concede alla tua app l’autorizzazione ad accedere all’API di Ahrefs per suo conto.
3. Ahrefs li reindirizza al tuo Redirect URI con:
   • parametro code — usato nel Passo 2
   • parametro state — verifica che corrisponda alla tua richiesta originale.

2. Recupera l’access_token

Scambia il code con un access_token inviando una richiesta POST a https://ahrefs.com/oauth/token .

Invia i parametri nel corpo della richiesta usando il formato application/x-www-form-urlencoded (vedi RFC6749 Sezione 4.1.3):

• grant_type: authorization_code
• client_id: {client_id} (Deve corrispondere a quello del Passo 1)
• redirect_uri: {redirect_uri} (Deve corrispondere a quello del Passo 1)
• code: {code} (Dal Passo 1)
• code_verifier: {original_code_verifier} (Il valore non trasformato del Passo 1)
• client_secret: {client_secret} (Solo per app web — si trova nella sezione Ahrefs Connect in Impostazioni account. Omettilo per le app desktop.)

Esempio di risposta:

{
    "access_token": "\<token to use in API requests>",
    "expires_in": \<lifetime of the access token in seconds>,
    "token_type": "Bearer",
    "scope": "apiv3-integration-apps"
}

Durata del Token e riconnessione

• Non vengono emessi refresh token.
• Gli access token sono validi per 1 anno. Dopo la scadenza, l’utente deve riconnettersi (ri-autorizzarsi) tramite OAuth.