Panduan OAuth

Semua panggilan API memerlukan otorisasi dan dilakukan atas nama pengguna Ahrefs yang telah diotorisasi. Untuk melakukannya, aplikasi Anda harus memperoleh token akses API untuk pengguna tersebut.

Ahrefs Connect menggunakan OAuth 2.0 Authorization Code Flow dengan Proof Key for Code Exchange (PKCE). Prosesnya memiliki dua langkah utama:

1. Otorisasi aplikasi

Arahkan pengguna ke:

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}

Parameter:

• {client_id} : Client ID yang di-URL-encode dari bagian Ahrefs Connect di Pengaturan akun Anda.
• {redirect_uri} : Redirect URI yang di-URL-encode yang telah Anda daftarkan di bagian yang sama.
• {code_challenge} : Diturunkan dari code verifier menggunakan metode S256:
  • Buat code verifier — string acak sepanjang 43–128 karakter dengan generator yang aman secara kriptografis. Karakter yang diizinkan: [A-Z] [a-z] [0-9] - . _ ~ (lihat RFC7636 Bagian 4.1).
  • Hitung hash SHA-256 dari code verifier.
  • Encode hash dengan Base64-URL.
  • Gunakan nilai yang sudah di-encode ini sebagai code_challenge (lihat RFC7636 Bagian 4.2).
• {state} : Buat nilai opaque untuk mempertahankan state antara permintaan dan callback. Server otorisasi akan menyertakan nilai ini saat mengalihkan pengguna kembali ke aplikasi Anda. (lihat RFC6749 Bagian 4.1.1)

Pengalaman pengguna:

1. Pengguna melihat layar persetujuan otorisasi Ahrefs.
2. Mereka memberikan izin kepada aplikasi Anda untuk mengakses Ahrefs API atas nama mereka.
3. Ahrefs mengalihkan mereka ke Redirect URI Anda dengan:
   • parameter code — digunakan pada Langkah 2
   • parameter state — verifikasi bahwa nilainya cocok dengan permintaan asli Anda.

2. Ambil access_token

Tukarkan code dengan access_token dengan mengirim permintaan POST ke https://ahrefs.com/oauth/token .

Kirim parameter di body permintaan menggunakan format application/x-www-form-urlencoded (lihat RFC6749 Bagian 4.1.3):

• grant_type: authorization_code
• client_id: {client_id} (Harus sama dengan yang ada di Langkah 1)
• redirect_uri: {redirect_uri} (Harus sama dengan yang ada di Langkah 1)
• code: {code} (Dari Langkah 1)
• code_verifier: {original_code_verifier} (Nilai asli yang belum ditransformasikan dari Langkah 1)
• client_secret: {client_secret} (Hanya untuk aplikasi web — terdapat di bagian Ahrefs Connect pada Pengaturan Akun. Abaikan untuk aplikasi desktop.)

Contoh respons:

{
    "access_token": "\<token untuk digunakan dalam permintaan API>",
    "expires_in": \<masa berlaku access token dalam detik>,
    "token_type": "Bearer",
    "scope": "apiv3-integration-apps"
}

Masa berlaku Token & penyambungan ulang

• Tidak ada refresh token yang diterbitkan.
• Token akses berlaku selama 1 tahun. Setelah kedaluwarsa, pengguna harus menyambungkan ulang (mengotorisasi ulang) melalui OAuth.