Authentication and Configuration

This page covers client configuration, the authentication model, and token management.

Client configuration

The PagFinanceClient receives a configuration object at construction time:

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

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

Configuration options

string

required

API host (Next.js proxy). Point it to your app today or to a dedicated BFF in the future. The contract stays the same.

string

required

Identifier of the application consuming the API.

object

Host application metadata.

Show properties

string

Default blockchain used when not specified per call (for example, solana).

Authentication model (challenge-response, no crypto)

The Web3 login is a challenge-response in the SIWS (Sign In With Solana) style. The SDK orchestrates the whole flow, and the host application only provides a signer that signs the challenge with the user’s wallet:

import nacl from 'tweetnacl';

const { tokenJWT } = await client.auth.signIn(
  { address, blockchain: 'solana' },
  (challenge) => wallet.signMessage(new TextEncoder().encode(challenge)),
);
// tokenJWT is stored in the client (tokenStore)

Internally the flow is: POST /api/auth/challenge, then signer(challenge), then POST /api/auth/verify. There is no cryptography or key in the client. The only proof is the signature, and all the logic (nonce, verification, token issuance) lives on the server.

Providing a token obtained elsewhere

If you already have a JWT token (obtained through another channel or reused from a previous session), just hand it to the client:

client.setToken(tokenJWT);

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

The SDK can sign in again automatically when the API responds 401, transparently to the application:

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

Authenticated endpoints require the JWT token to be present in the client, either via signIn or via setToken. Public endpoints (such as assets.acceptedCryptos) do not need a token.

Authentication methods

Method	Description
`auth.signIn(params, signer)`	Runs the complete challenge-response flow and stores the token.
`auth.challenge(params)`	Requests the challenge (nonce) from the server.
`auth.verify(params)`	Verifies the signature and receives the JWT token.
`auth.setToken(token)`	Sets the JWT token on the client.
`auth.getToken()`	Returns the currently stored token.
`auth.clearToken()`	Removes the token from the client.
`auth.otpSend(params)`	Sends an OTP code.
`auth.enableAutoRelogin(fn)`	Enables automatic re-login on 401 responses.

See the Method Reference for the complete list of resources and the Authentication API Reference for the underlying REST endpoints.

​Client configuration

​Configuration options

​Authentication model (challenge-response, no crypto)

​Providing a token obtained elsewhere

​Transparent re-login on 401

​Authentication methods

Client configuration

Configuration options

Authentication model (challenge-response, no crypto)

Providing a token obtained elsewhere

Transparent re-login on 401

Authentication methods