Skip to main content

​
Requirements

The Align SDK requires Node.js 18.0.0 or higher and works with any modern JavaScript runtime including Bun and Deno.
RequirementVersion
Node.js≥ 18.0.0
TypeScript≥ 5.0.0 (optional but recommended)

​
Package Installation

Install the SDK using your preferred package manager:
npm install @tolbel/align

​
TypeScript Configuration

TypeScript is optional but highly recommended. The SDK provides full type definitions out of the box.
For the best development experience, ensure your tsconfig.json includes: 
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

​
Environment Setup

​
Getting Your API Key

API Access is Gated — The Align API is not publicly available. You must contact the Align team to request API access and obtain your credentials.
1

Contact Align

Reach out to the Align team or their sales department to request API access. API keys are provisioned on a case-by-case basis.
2

Get Sandbox Key

Once approved, navigate to Settings → API Keys in your dashboard and copy your sandbox API key
3

Store Securely

Add your API key to environment variables (never commit to version control!)

​
Environment Variables

Production Security Best Practice — For production environments, always store API keys in a secure secrets manager like AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, or your cloud provider’s equivalent. Never hard-code secrets in your application.For local development only, you may use a .env file.
Create a .env file in your project root for local development: 
# .env (LOCAL DEVELOPMENT ONLY)
ALIGN_API_KEY=your_sandbox_api_key_here
ALIGN_ENVIRONMENT=sandbox
Add .env to your .gitignore file to prevent accidentally committing secrets to version control.

​
Verify Installation

Create a test file to verify the SDK is working: 
import Align from "@tolbel/align";

const align = new Align({
  apiKey: process.env.ALIGN_API_KEY!,
  environment: "sandbox",
});

// Test the connection by listing customers
async function test() {
  try {
    const customers = await align.customers.list();
    console.log("SDK connected successfully!");
    console.log(`Found ${customers.items.length} customers`);
  } catch (error) {
    console.error("Connection failed:", error);
  }
}

test();
Run the test:
npx tsx test.ts

​
Troubleshooting

Ensure you have the correct moduleResolution in your TypeScript config:
{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}
For CommonJS projects, use "moduleResolution": "node" instead.
The SDK is designed for TypeScript strict mode. If you see type errors, ensure your tsconfig.json has:
{
  "compilerOptions": {
    "strict": true
  }
}
  1. Verify you’re using the correct environment (sandbox vs production)
  2. Check that your API key is correctly formatted (no extra spaces)
  3. Ensure your account has API access enabled

​
Next Steps

Quick Start Guide

Learn how to create your first customer and process payments