Autenticação e Configuração

Esta página cobre a configuração do cliente, o modelo de autenticação e a gestão de tokens.

Configuração do cliente

O PagFinanceClient recebe um objeto de configuração na construção:

import { PagFinanceClient } from '@pagfinance/sdk';

const client = new PagFinanceClient({
  baseUrl: 'https://app.pag.finance',
  clientId: 'meu-app',
  appMeta: { name: 'meu-app', version: '1.0.0', domain: 'meuapp.com' },
  defaultBlockchain: 'solana',
});

Opções de configuração

baseUrl

string

required

Host da API (proxy Next.js). Aponte para o seu app hoje ou para um BFF dedicado no futuro. O mesmo contrato se mantém.

clientId

string

required

Identificador da aplicação que está consumindo a API.

appMeta

object

Metadados da aplicação host.

Show propriedades

defaultBlockchain

string

Blockchain padrão usada quando não especificada por chamada (por exemplo, solana).

Modelo de autenticação (challenge-response, sem cripto)

O login Web3 é um challenge-response no estilo SIWS (Sign In With Solana). O SDK orquestra todo o fluxo, e a aplicação host apenas fornece um signer que assina o desafio com a carteira do usuário:

import nacl from 'tweetnacl';

const { tokenJWT } = await client.auth.signIn(
  { address, blockchain: 'solana' },
  (challenge) => wallet.signMessage(new TextEncoder().encode(challenge)),
);
// tokenJWT já fica salvo no client (tokenStore)

Internamente o fluxo é: POST /api/auth/challenge, então signer(challenge), então POST /api/auth/verify. Não há criptografia nem chave no cliente. A única prova é a assinatura, e toda a lógica (nonce, verificação, emissão do token) vive no servidor.

Fornecendo um token obtido por fora

Se você já possui um token JWT (obtido por outro canal ou reaproveitado de sessão anterior), basta informá-lo ao cliente:

client.setToken(tokenJWT);

const me = await client.user.me();

O SDK pode refazer o login automaticamente quando a API responde 401, de forma transparente para a aplicação:

client.auth.enableAutoRelogin(async () => {
  await client.auth.signIn({ address, blockchain }, signer);
  return true;
});

Endpoints autenticados exigem que o token JWT esteja presente no cliente, seja via signIn, seja via setToken. Endpoints públicos (como assets.acceptedCryptos) não precisam de token.

Métodos de autenticação

Método	Descrição
`auth.signIn(params, signer)`	Executa o fluxo completo challenge-response e salva o token.
`auth.challenge(params)`	Solicita o desafio (nonce) ao servidor.
`auth.verify(params)`	Verifica a assinatura e recebe o token JWT.
`auth.setToken(token)`	Define o token JWT no cliente.
`auth.getToken()`	Retorna o token atual armazenado.
`auth.clearToken()`	Remove o token do cliente.
`auth.otpSend(params)`	Envia um código OTP.
`auth.enableAutoRelogin(fn)`	Habilita re-login automático em respostas 401.

Consulte a Referência de Métodos para a lista completa de recursos e a API Reference de Autenticação para os endpoints REST subjacentes.

​Configuração do cliente

​Opções de configuração

​Modelo de autenticação (challenge-response, sem cripto)

​Fornecendo um token obtido por fora

​Re-login transparente em 401

​Métodos de autenticação

Configuração do cliente

Opções de configuração

Modelo de autenticação (challenge-response, sem cripto)

Fornecendo um token obtido por fora

Re-login transparente em 401

Métodos de autenticação