Configuration

AlviereCoreConfig

All fields are optional. Pass the config object to the AlviereCore constructor, or call configure() later to update specific fields.

import { AlviereCore } from '@alviere/core';

const core = new AlviereCore({
  jwt: 'your-sierra-api-v3-jwt',
  publicCertificate: 'your-rsa-pem',
  publicCertificateId: 'cert-id',
  debug: false,
});

Fields

Field	Type	Description
`jwt`	`string`	Sierra API v3 JWT. Drives the API domain, RSA certificate selection, and the `account_uuid` (from the `sub` claim). Required for any authenticated service call.
`publicCertificate`	`string`	RSA public key in PEM format. Required for service calls that encrypt their payload (card data, sensitive PII).
`publicCertificateId`	`string`	Identifier for the RSA key. Must match the key registered in Alcore. Required alongside `publicCertificate`.
`business_uuid`	`string`	UUID of the business account. Used by `isFirstTimeUser()` and `isScopedToPayee()` to determine the relationship between the JWT subject and the business.
`debug`	`boolean`	Enables verbose logging via the internal `Logger`. Defaults to `false`.
`alviere`	`Partial<AlviereConfig>`	Runtime overrides for Alcore connection parameters (domain, access token, certificate). Advanced — only needed when overriding the JWT-derived defaults.

The domain field is present in the TypeScript type for legacy reasons but is not read by the constructor. The API domain is derived automatically from the jwt via the embedded AlviereConfig. To override the domain, use alviere.domain.

Updating config at runtime

configure() accepts a partial config and merges it with the existing configuration. Changing jwt automatically clears the internal request cache.

// After generating a scoped token
const scopedJwt = await core.generateScopedToken('account-uuid');
core.configure({ jwt: scopedJwt });

// Enable debug logging at any time
core.configure({ debug: true });

configure() returns this so calls can be chained:

core
  .configure({ jwt: businessJwt })
  .configure({ debug: true });

JWT structure

The JWT must be a Sierra API v3 token. AlviereCore reads the following claims:

Claim	Used for
`sub`	Account UUID — returned by `getAccountUuid()`
`api_domain`	Alcore endpoint the SDK communicates with
`exp`	Not validated client-side; Alcore enforces expiry

Example JWT payload:

{
  "api_domain": "https://api.dev.alviere.com",
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "exp": 1717526400
}

Environment-specific setup

Your backend should provide the JWT, certificate, and certificate ID for each session. The SDK does not store credentials between page loads.

// Example: initialise from a server-side session response
const { jwt, publicCertificate, publicCertificateId } = await fetchSession();

const core = new AlviereCore({
  jwt,
  publicCertificate,
  publicCertificateId,
  debug: import.meta.env.DEV,
});

Getting Started

AlviereCore API