Authentication & Environment Setup

This guide explains how authentication works when using the Newline TypeScript SDK and how to configure your application to communicate with the correct Newline environment. Proper setup is required before making any SDK calls.

Authentication Model

The Newline TypeScript SDK authenticates using program‑level credentials. These credentials identify your program and are used to sign API requests.

Authentication is based on:

• Program UID — Identifies your Newline program
• HMAC key — Used to cryptographically sign requests

These credentials are issued during program provisioning and are required for all API access.

The SDK uses the same authentication model as direct API integrations. There is no separate SDK‑specific authentication mechanism.

Storing Credentials Securely

Credentials should be stored using environment variables, not hard‑coded into application source code. This reduces the risk of accidental exposure and simplifies environment‑specific configuration.

Required Environment Variables

macOS / Linux (bash, zsh)

export NEWLINE_PROGRAM_UID="your_program_uid"
export NEWLINE_HMAC_KEY="your_hmac_key"

Windows (PowerShell)

setx NEWLINE_PROGRAM_UID "your_program_uid"
setx NEWLINE_HMAC_KEY "your_hmac_key"

After setting environment variables, restart your terminal or runtime so the values are available to the application.

Initializing the SDK with Credentials

Credentials are provided to the SDK during client initialization using the security configuration option.

import { NewlineSDK } from "newline-ts-sdk";

const newlineSDK = new NewlineSDK({
  server: "sandbox",
  security: {
    programUid: process.env.NEWLINE_PROGRAM_UID ?? "",
    hmacKey: process.env.NEWLINE_HMAC_KEY ?? "",
  },
});

The SDK reads credentials at runtime and applies them automatically to all requests made through the client instance.

Environment Selection

Newline provides separate environments for development and production use. The SDK must be configured to use the correct environment.

Available Environments

Environment selection is controlled using the server option during SDK initialization.

const newlineSDK = new NewlineSDK({
  server: "sandbox",
  security: {
    programUid: process.env.NEWLINE_PROGRAM_UID ?? "",
    hmacKey: process.env.NEWLINE_HMAC_KEY ?? "",
  },
});

Environment Guidance

• Always begin development in the sandbox environment
• The sandbox environment supports testing and simulation workflows
• Switch to prod only after your integration has been validated and approved
• Environment selection affects endpoints, data visibility, and transaction behavior

Credential and Environment Isolation

Best practices include:

• Using separate credentials for sandbox and production environments
• Isolating environment variables by deployment environment
• Avoiding reuse of production credentials in development or test systems

This reduces the risk of unintended access to live systems and data.

Common Authentication Issues

If authentication fails, verify the following:

• Environment variables are correctly set and accessible at runtime
• The correct environment (sandbox vs prod) is selected
• Program credentials are valid and active
• The application was restarted after setting environment variables

Authentication errors returned by the SDK include structured status codes and messages that can be used for troubleshooting.

Next Step

With authentication and environment configuration complete, you can begin using the SDK to interact with Newline resources.

Continue to Using the SDK to learn common workflows such as retrieving transactions, initiating transfers, and handling errors.