Docs SDK @holdify/sdk

@holdify/sdk

The core Holdify SDK for JavaScript and TypeScript.

Installation

Terminal

bash

npm install @holdify/sdk
# or
yarn add @holdify/sdk
# or
pnpm add @holdify/sdk

Quick start

Basic usage

typescript

import { Holdify } from '@holdify/sdk';

const holdify = new Holdify({
  apiKey: process.env.HOLDIFY_PROJECT_KEY,
});

const result = await holdify.verify('hk_live_xxx');

if (result.valid) {
  console.log(`Remaining: ${result.remaining}`);
}

Configuration

Configuration options

typescript

const holdify = new Holdify({
  // Required: Your project API key
  apiKey: 'hpk_live_xxx',

  // Optional: Custom API URL (for self-hosted)
  baseUrl: 'https://api.holdify.io',

  // Optional: Request timeout in ms (default: 10000)
  timeout: 5000,
});

Option	Type	Default	Description
apiKey	string	-	Your project API key (required)
baseUrl	string	https://api.holdify.io	API base URL
timeout	number	10000	Request timeout in ms

Methods

verify(key)

Verify an API key and check rate limits.

verify()

typescript

// Simple verification
const result = await holdify.verify('hk_live_xxx');

// With options
const result = await holdify.verify({
  key: 'hk_live_xxx',
  resource: 'api-calls',  // Optional: resource type for usage tracking
  units: 1,               // Optional: units to consume
});

Response

VerifyResult

typescript

{
  valid: true,
  remaining: 9999,        // Requests remaining in period
  limit: 10000,           // Total limit
  reset: 1704067200,      // Unix timestamp when limit resets
  plan: 'pro',            // Customer's plan
  entitlements: ['feature:x', 'feature:y']
}

createKey(options)

Create a new API key for a customer.

createKey()

typescript

const key = await holdify.createKey({
  name: 'Production Key',
  tenantId: 'customer_123',  // Link to customer
  scopes: ['read', 'write'], // Optional: permissions
  metadata: { customerId: '123' }, // Optional: custom data
});

// IMPORTANT: key.key is only returned once!
console.log('Save this key:', key.key);

listKeys()

List all API keys for your project.

listKeys()

typescript

const { keys } = await holdify.listKeys();

keys.forEach(key => {
  console.log(`${key.name}: ${key.prefix}...${key.secretLast4}`);
});

revokeKey(keyId)

Permanently revoke an API key.

revokeKey()

typescript

await holdify.revokeKey('key_xxx');

rotateKey(keyId)

Generate a new secret for an existing key.

rotateKey()

typescript

const newKey = await holdify.rotateKey('key_xxx');

// IMPORTANT: newKey.key contains the new secret
// Old key remains valid for grace period (default: 24h)

trackUsage(event, idempotencyKey?)

Track a usage event.

trackUsage()

typescript

await holdify.trackUsage({
  keyId: 'key_xxx',
  resource: 'api-calls',
  units: 1,
}, 'unique-request-id');  // Optional: prevents duplicate tracking

Error handling

typescript

import { Holdify, HoldifyError } from '@holdify/sdk';

try {
  await holdify.verify('invalid-key');
} catch (error) {
  if (error instanceof HoldifyError) {
    console.log(error.code);       // 'INVALID_KEY'
    console.log(error.message);    // 'API key is invalid'
    console.log(error.statusCode); // 401
  }
}

Error codes

Code	Description
INVALID_KEY	API key is invalid or not found
KEY_REVOKED	API key has been revoked
KEY_DISABLED	API key is temporarily disabled
RATE_LIMIT_EXCEEDED	Too many requests
QUOTA_EXCEEDED	Monthly quota exhausted
MISSING_KEY	No API key provided
UNAUTHORIZED	Invalid project API key

TypeScript

Full TypeScript support included:

Type imports

typescript

import type {
  VerifyResult,
  ApiKey,
  HoldifyConfig
} from '@holdify/sdk';