Authentication

The SDK authenticates using API keys and manages access/refresh tokens automatically.

Credentials

Parameter	Type	Required	Description
apiBase	string	Yes	Base URL for the API (e.g. https://api.example.com/public/v1)
apiKey	string	Yes	Your integrator API key
apiSecret	string	Yes	Your integrator API secret
tenant	string	Yes	Tenant UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
country	string	No	Two-letter ISO country code (e.g. CO, MX)

Client options

type HeuristikClientOptions = {
  apiBase: string;
  apiKey: string;
  apiSecret: string;
  tenant: string;
  country?: string | null;
  defaultHeaders?: Record<string, string>;
};

Login

client.init() loads stored tokens and performs login if needed:

const client = new HeuristikClient({
  apiBase: 'https://api.example.com/public/v1',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
  tenant: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  country: 'CO',
});

await client.init();
// client is now authenticated
console.log(client.accessToken); // string | null

The tokens are stored in memory and persisted via the StorageProvider.

In case of failure, consult the documentation related to the different types of errors and the examples of their handling, here: Error handling

Token refresh

Refresh the access token using the current refresh token:

await client.refreshToken();

This updates both tokens in memory and storage.

Token lifetimes

Token	Duration
Access token	10 hours
Refresh token	24 hours

The developer is responsible for refreshing tokens before they expire and for storing them securely. See Storage for persistence options.

In case of failure, consult the documentation related to the different types of errors and the examples of their handling, here: Error handling

Logout

Close the session and clear all tokens:

await client.logout();

This clears tokens from memory and storage.

Security

Never expose apiKey or apiSecret in client-side code for production applications. Use a server-side proxy to manage credentials.

Authenticated requests

Use client.auth.request(url, init?) for all API calls. It automatically merges SDK default headers, the Authorization token, and converts network failures into NetworkError.

In case of failure, consult the documentation related to the different types of errors and the examples of their handling, here: Error handling