> For the complete documentation index, see [llms.txt](https://docs.autentique.com.br/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.autentique.com.br/api/2/integracao/oauth2/autorizando-um-usuario.md).

# Autorizando um usuário

Nesta etapa, sua integração envia o usuário para o Autentique. O usuário entra na conta, confere as permissões solicitadas e decide se deseja conceder o acesso.

Antes de continuar, crie um aplicativo OAuth e tenha em mãos:

* o `Client ID`;
* a URL de redirecionamento cadastrada;
* as permissões que serão solicitadas.

O `Client Secret` ainda não será enviado ao navegador. Ele será usado somente pelo backend na troca do código pelos tokens.

### Proteja cada tentativa de autorização

Antes de redirecionar o usuário, crie três valores:

| Valor            | Para que serve                                                                                      |
| ---------------- | --------------------------------------------------------------------------------------------------- |
| `state`          | Vincula o callback à tentativa iniciada pela sua integração e ajuda a impedir requisições forjadas. |
| `code_verifier`  | Segredo temporário, criado especificamente para aquela tentativa de autorização.                    |
| `code_challenge` | Versão derivada do `code_verifier`, enviada ao Autentique sem expor o valor original.               |

Crie valores novos para cada tentativa. O `code_verifier` deve ter de 43 a 128 caracteres e o desafio deve usar `S256`.

O exemplo abaixo usa Web Crypto e funciona em runtimes JavaScript que oferecem `crypto.subtle`:

```javascript
const base64url = (bytes) =>
  btoa(String.fromCharCode(...bytes))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');

const randomValue = (length = 32) =>
  base64url(crypto.getRandomValues(new Uint8Array(length)));

export async function createOAuthSession() {
  const state = randomValue();
  const codeVerifier = randomValue(64); // 86 caracteres, dentro do limite PKCE

  const digest = await crypto.subtle.digest(
    'SHA-256',
    new TextEncoder().encode(codeVerifier),
  );

  return {
    state,
    codeVerifier,
    codeChallenge: base64url(new Uint8Array(digest)),
  };
}
```

Guarde o `state` e o `codeVerifier` em uma sessão temporária no servidor, vinculada ao usuário que iniciou a conexão. Defina uma expiração curta e remova a sessão depois que o callback for processado.

Se sua arquitetura gerar esses valores no navegador, transfira-os imediatamente para a sessão temporária no servidor. Não reutilize os valores e não mantenha o `codeVerifier` no armazenamento do navegador.

### Monte a URL de autorização

O endpoint de autorização é:

```
https://api.autentique.com.br/oauth/authorize
```

Envie os seguintes parâmetros:

| Parâmetro               | Valor                                          |
| ----------------------- | ---------------------------------------------- |
| `client_id`             | Client ID do aplicativo.                       |
| `redirect_uri`          | URL cadastrada no aplicativo.                  |
| `response_type`         | Use `code`.                                    |
| `scope`                 | Permissões solicitadas, separadas por espaços. |
| `state`                 | Valor temporário criado pela integração.       |
| `code_challenge`        | Desafio derivado do `code_verifier`.           |
| `code_challenge_method` | Use `S256`.                                    |

Exemplo:

```javascript
const url = new URL('https://api.autentique.com.br/oauth/authorize');

url.search = new URLSearchParams({
  client_id: process.env.AUTENTIQUE_CLIENT_ID,
  redirect_uri: process.env.AUTENTIQUE_REDIRECT_URI,
  response_type: 'code',
  scope: 'user:read documents:read',
  state: oauthSession.state,
  code_challenge: oauthSession.codeChallenge,
  code_challenge_method: 'S256',
  // prompt: 'consent',
}).toString();

return url.toString();
```

O valor de `scope` deve conter apenas permissões configuradas para o aplicativo. Separe múltiplas permissões com espaços.

Use `prompt=consent` somente quando precisar mostrar novamente a tela de consentimento.

Redirecione o navegador do usuário para a URL gerada. Não faça uma requisição AJAX para o endpoint de autorização.

### Receba o callback

Depois da decisão do usuário, o Autentique redireciona o navegador para a URL cadastrada.

Se o acesso for aprovado, o callback terá `code` e `state`:

```
https://app.exemplo.com/integracoes/autentique/callback?code=CODIGO&state=VALOR
```

Antes de usar o código:

1. localize a sessão temporária daquela autorização;
2. compare o `state` retornado com o valor salvo;
3. confirme que a sessão ainda não expirou;
4. remova ou marque a sessão como utilizada.

Se o `state` estiver ausente ou for diferente, encerre a tentativa. Não troque o código por tokens.

O código de autorização é temporário, de uso único e vinculado ao aplicativo, à URL de redirecionamento e ao `code_verifier` daquela tentativa.

### Trate uma autorização negada

Se o usuário negar o acesso ou a autorização não puder ser concluída, o callback poderá conter:

* `error`;
* `error_description`;
* `state`.

Por exemplo:

```
https://app.exemplo.com/integracoes/autentique/callback?error=access_denied&state=VALOR
```

Valide o `state` também nos retornos com erro. Depois, informe que a conexão não foi concluída e permita que o usuário tente novamente se desejar.

Não trate uma negativa como falha inesperada e não inicie outra autorização automaticamente.

Com o callback validado, continue em Obtendo e usando os tokens.