> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Início rápido em JavaScript

> Ligue a aplicação de autenticação Didit ao início de sessão alojado com PKCE, validação de callback, verificação de sessões e terminar sessão.

> [!WARNING]
>
> A autenticação é nova: use este exemplo de fluxo alojado com uma aplicação que tenha a Autenticação ativada. O pacote `@didit-protocol/auth` ainda não está publicado; a API do pacote abaixo é uma pré-visualização, não um guia de início rápido instalável.

## Configurar o início de sessão alojado

Registe o URL de retorno exato e a origem web da sua aplicação de sandbox. Copie a origem de início de sessão (`https://<slug>.sandbox.auth.didit.me`) a partir da consola, como descrito na [visão geral](https://docs.didit.me/pt/authentication/overview.md). Este exemplo usa as APIs de criptografia do navegador e exige HTTPS, ou localhost no sandbox: consulte [desenvolvimento local](https://docs.didit.me/pt/authentication/overview.md#desenvolvimento-local) para saber o que deve registar.

A aplicação é responsável pelo `state` e pelo verificador PKCE. O início de sessão alojado é responsável pelos ecrãs de palavra-passe, e-mail, passkey, telefone, SSO e MFA obrigatório. Nenhuma chave de API deve estar neste código.

```javascript auth.js theme={null}
// Replace both values with your registered application configuration.
const AUTH_BASE = "https://YOUR_SLUG.sandbox.auth.didit.me/";
const REDIRECT_URI = "https://YOUR_APP_ORIGIN/auth/callback";
const PENDING = "didit.auth.pending";
let tokens = null;

function base64url(bytes) {
  return btoa(String.fromCharCode(...bytes))
    .replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
}

export async function signIn() {
  const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
  const state = base64url(crypto.getRandomValues(new Uint8Array(32)));
  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
  sessionStorage.setItem(PENDING, JSON.stringify({ verifier, state, startedAt: Date.now() }));
  const url = new URL("sign-in", AUTH_BASE);
  url.search = new URLSearchParams({
    redirect_uri: REDIRECT_URI,
    state,
    code_challenge: base64url(new Uint8Array(digest)),
    code_challenge_method: "S256",
  }).toString();
  window.location.assign(url.href);
}

export async function handleCallback() {
  const query = new URLSearchParams(window.location.search);
  const saved = sessionStorage.getItem(PENDING);
  sessionStorage.removeItem(PENDING);
  history.replaceState(null, "", window.location.pathname);
  if (!saved) throw new Error("Start sign-in again.");
  const pending = JSON.parse(saved);
  if (query.get("state") !== pending.state || Date.now() - pending.startedAt > 600000) {
    throw new Error("Invalid or expired sign-in. Start again.");
  }
  if (query.has("error") || !query.get("code")) throw new Error("Sign-in was not completed.");
  const response = await fetch(new URL("token/", AUTH_BASE), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "authorization_code",
      code: query.get("code"),
      code_verifier: pending.verifier,
      redirect_uri: REDIRECT_URI,
    }),
  });
  if (!response.ok) throw new Error("Code exchange failed. Start sign-in again.");
  tokens = await response.json();
  return getSession();
}

export async function getSession() {
  if (!tokens) return null;
  const response = await fetch(new URL("session/", AUTH_BASE), {
    headers: { Authorization: `Bearer ${tokens.access_token}` },
    cache: "no-store",
  });
  if (!response.ok) {
    tokens = null;
    throw new Error("Session check failed. Sign in again.");
  }
  return response.json();
}

export async function signOut() {
  const current = tokens;
  tokens = null;
  if (!current) return;
  const response = await fetch(new URL("session/", AUTH_BASE), {
    method: "DELETE",
    headers: { Authorization: `Bearer ${current.access_token}` },
  });
  if (response.status !== 204) throw new Error("Local state cleared; server logout failed.");
}
```

Chame `signIn()` a partir do botão de início de sessão. Na página de retorno registada, chame `handleCallback()` uma vez, mostre um estado de carregamento e apresente o erro, se falhar. Use `getSession()` para obter o utilizador atual e `signOut()` para terminar a sessão. A função de retorno remove o código da barra de endereços antes de fazer qualquer pedido.

Este exemplo mínimo mantém os tokens em memória e volta a iniciar sessão após um recarregamento da página ou quando o token de acesso expira. Para sessões persistentes, use o seu backend e cookies seguros, ou implemente a [rotação de tokens de atualização](https://docs.didit.me/pt/authentication/tokens-and-jwks.md) com serialização. Nunca coloque tokens de atualização em URLs ou registos. A verificação de sessão no frontend controla apenas a apresentação; o seu backend deve validar quem faz o pedido em cada pedido protegido.

## Pré-visualização da versão do SDK de autenticação

O núcleo planeado `@didit-protocol/auth` expõe `createDiditAuth({publishableKey})`, `signIn()`, `handleRedirectCallback()`, `getSession()`, `getToken()`, `onAuthStateChange` e `signOut()`, com `vendorData` na identidade. Destina-se a acrescentar sinais automáticos do dispositivo e um ponto de entrada no servidor com `verifyToken()`.

A chave publicável é `pk_live_` (aplicação de produção) ou `pk_test_` (aplicação de sandbox), seguida da codificação base64url, sem preenchimento, da origem da sua aplicação.
O SDK envia os seus pedidos de API para essa origem.
A chave é pública: identifica a aplicação e não é um segredo.

### Verificação adicional e reautenticação na pré-visualização

* `stepUp({ action, amount?, currency?, redirectUri? })` chama o `POST step-up/` da sua aplicação para perguntar se `action` requer uma verificação de identidade.
  `action` é `payout`, `bank` ou `contact`, e um payout requer `amount`.
  Quando se aplica uma das suas regras de verificação adicional, navega para a página de verificação que a Didit devolve.
* `handleStepUpCallback(url?)` é executado na página para onde a pessoa regressa.
  Lê `?step_up=<id>`, remove-o da barra de endereços e lê o resultado com `GET step-up/{id}/`.
* `reauthenticate({ method? })` volta a autenticar a mesma pessoa, na página alojada (`method: "redirect"`, o padrão) ou com uma chave de acesso (`method: "passkey"`, apenas no domínio de início de sessão da sua aplicação na Didit).
  Depois da página alojada, conclua com `handleRedirectCallback()`.
  Se outra pessoa concluir o processo, este é rejeitado com `step_up_user_mismatch` e a sessão original mantém-se.

Ambos os métodos de verificação adicional devolvem `{ id, status, approved, rule, method }`, em que `status` é `not_required`, `pending`, `approved`, `review`, `declined` ou `expired`.
`redirectUri` assume por predefinição o endereço de redirecionamento do cliente e tem de corresponder exatamente a um dos endereços de redirecionamento registados da sua aplicação: quando é necessária uma verificação, a Didit recusa qualquer outro endereço.
Antes de o seu backend agir sobre uma verificação adicional, leia-a novamente com `GET step-up/{id}/` e com o token de acesso da pessoa, porque um resultado comunicado pelo navegador pode ser alterado.

Um início de sessão sem interface gráfica (headless) também pode responder `protection_required` quando as regras de proteção da sua aplicação o assinalam.
A pessoa conclui-o então com o código que a Didit lhe enviou por e-mail (`protection.verify({ code })`) ou com uma passkey (`protection.passkey()`), e `methods` indica quais dos dois pode utilizar.

Não instale uma versão baseada em suposições nem escreva com base em opções de callback presumidas. Confirme as exportações do pacote publicado, o emissor e a configuração das chaves antes de substituir o exemplo alojado. Palavra-passe, código por e-mail, ligação mágica, passkey, telefone, MFA, início de sessão social, verificação adicional e métodos de agente dependerão da API suportada por essa versão.

## Adicionar outros produtos

O seu backend verifica o token de acesso (consulte [tokens e JWKS](https://docs.didit.me/pt/authentication/tokens-and-jwks.md)) e lê o respetivo `vendor_data`. Use esse valor como `vendor_data` ao [criar uma sessão de verificação](https://docs.didit.me/pt/sessions-api/create-session.md) ou ao [emitir um token de transação](https://docs.didit.me/pt/transaction-monitoring/sdk-transaction-submission.md). Um início de sessão bem-sucedido não significa que qualquer dos produtos tenha aprovado o utilizador.

Antes de publicar, teste o registo, o início de sessão de utilizadores recorrentes, o cancelamento, um state que não corresponde, um código reutilizado, a recuperação de palavra-passe, o MFA, a expiração e o terminar de sessão na sua aplicação de sandbox com a Autenticação ativada.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.