How To Start - Ahrefs API

Ahrefs API v2 has been deprecated

This documentation is for the legacy version of our API (v2), which was discontinued on March 1st, 2024. Existing API v2 integration apps are not affected and continue to work as before, but new submissions are no longer accepted.

To switch to API v3, please contact our Enterprise team. Read about API v3.

Integrations - How to Start

API calls require authorization, and are made on behalf of an authorized user. In order to do that, an application will need to be granted an API access token from user. The procedure is different depending on the application type (web or desktop).

For web applications:

1. Generate the "state" request parameter (opaque to the user) to maintain state between request and callback (see RFC6749 section 4.1.1).
2. Redirect the user to the invitation URL shown in your apps list, appending the generated "state" parameter to the request.
3. The user will see the authorization prompt. If he or she chooses to authorize your application to spend API rows, the service will redirect the user back to the redirect URL provided by you when submitting your application.
4. Check the "state" parameter to make sure the callback was made for your request.
5. The callback request will include the "code" parameter your application must use when requesting the access token.
6. Send a POST request to https://ahrefs.com/oauth2/token.php using the following parameters (see RFC6749 Section 4.1.3)
- grant_type=authorization_code
- code=<code from the previous step>
- client_id=<client id of your application>
- client_secret=<client secret of your application>
- redirect_uri=<redirect URI of your application>

7. If the access token request is valid and authorized, the service will return the successful JSON response:

{
    "access_token":"<token you can use when performing API requests>",
    "expires_in":<expiry interval>,
    "token_type":"bearer",
    "scope":"api",
    "refresh_token":"<token you can use to retrieve the new API token>"
}

For desktop applications:

1. Generate the "state" request parameter (opaque to the user) to maintain state between request and callback (see RFC6749 section 4.1.1).
2. Redirect the user to the invitation URL shown in your apps list, appending the generated "state" parameter to the request.
3. The user will see the authorization prompt. If he or she chooses to authorize your application to spend API rows, the service will redirect the user back to the redirect URL provided by you when submitting your application.
4. Check the "state" parameter to make sure the callback was made for your request.
5. The callback request will include the "token" parameter you can use when performing API requests.