Guia de OAuth

Todas as chamadas de API exigem autorização e são feitas em nome de um usuário Ahrefs autorizado. Para isso, seu app precisa obter um token de acesso à API para esse usuário.

O Ahrefs Connect usa o Fluxo de Código de Autorização do OAuth 2.0 com Proof Key for Code Exchange (PKCE). O processo tem duas etapas principais:

1. Autorizar o aplicativo

Redirecione o usuário para:

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} : Client ID codificado em URL da seção Ahrefs Connect nas suas Configurações da conta.
• {redirect_uri} : Redirect URI codificado em URL que você registrou na mesma seção.
• {code_challenge} : Derivado de um code verifier usando o método S256:
  • Gere um code verifier — uma string aleatória de 43 a 128 caracteres usando um gerador criptograficamente seguro. Caracteres permitidos: [A-Z] [a-z] [0-9] - . _ ~ (consulte a Seção 4.1 da RFC7636).
  • Calcule o hash SHA-256 do code verifier.
  • Codifique o hash em Base64-URL.
  • Use esse valor codificado como code_challenge (consulte a Seção 4.2 da RFC7636).
• {state} : Gere um valor opaco para manter o estado entre a solicitação e o callback. O servidor de autorização incluirá esse valor ao redirecionar o usuário de volta para o seu app. (consulte a Seção 4.1.1 da RFC6749)

Experiência do usuário:

1. O usuário vê a tela de consentimento de autorização da Ahrefs.
2. Ele concede ao seu app permissão para acessar a API da Ahrefs em nome dele.
3. A Ahrefs os redireciona para sua URI de redirecionamento com:
   • parâmetro code — usado na Etapa 2
   • parâmetro state — verifique se ele corresponde à sua solicitação original.

2. Obtenha o access_token

Troque o code por um access_token enviando uma solicitação POST para https://ahrefs.com/oauth/token .

Envie os parâmetros no corpo da solicitação usando o formato application/x-www-form-urlencoded (consulte a Seção 4.1.3 da RFC6749):

• grant_type: authorization_code
• client_id: {client_id} (Deve corresponder ao da Etapa 1)
• redirect_uri: {redirect_uri} (Deve corresponder ao da Etapa 1)
• code: {code} (Da Etapa 1)
• code_verifier: {original_code_verifier} (O valor sem transformação da Etapa 1)
• client_secret: {client_secret} (Somente apps web — encontrado na seção Ahrefs Connect em Configurações da conta. Omitir para apps desktop.)

Exemplo de resposta:

{
    "access_token": "\<token a ser usado em requisições à API>",
    "expires_in": \<tempo de vida do access token em segundos>,
    "token_type": "Bearer",
    "scope": "apiv3-integration-apps"
}

Duração do token e reconexão

• Nenhum token de atualização é emitido.
• Os tokens de acesso são válidos por 1 ano. Após a expiração, o usuário deve reconectar (reautorizar) via OAuth.