SDK Overview

Installation

pnpm

pnpm add @rakomi/node

npm

npm install @rakomi/node

yarn

yarn add @rakomi/node

Design principles

• 1 runtime dependency — only jose for JWT/JWKS operations
• ESM-first — ships as ES modules. CJS supported via Node.js require(esm)
• Result pattern — verifyToken() and verifyWebhook() never throw. They return { ok: true, data } or { ok: false, error }
• Lazy initialization — no network calls until the first verifyToken() call
• Type-safe — full TypeScript types with generic payload support
• Zero memory leaks — JWKS cache holds exactly 1 entry, replaced on refresh

Quick start

import { Rakomi } from '@rakomi/node';

const ca = new RakomiClient({
  apiKey: 'akm_live_xxx', // Replace with your API key
});

// Verify a JWT access token
const result = await ca.verifyToken(token);
if (result.ok) {
  console.log('User ID:', result.data.userId);
  console.log('Email:', result.data.email);
} else {
  console.error('Error:', result.error.code);
  console.error('Fix:', result.error.suggestion);
}

Configuration

const ca = new RakomiClient({
  // Required
  apiKey: 'akm_live_xxx',

  // Optional
  baseUrl: 'https://api.rakomi.com',   // Default API URL
  clockTolerance: 30,                       // JWT expiry tolerance in seconds (max: 120)
  environment: 'production',                // Override auto-detection ('development' | 'production')
  webhookSecret: 'whsec_xxx',              // For webhook signature verification
  webhookTolerance: 300,                    // Webhook timestamp tolerance in seconds (max: 600)
});

API key format

API keys must start with akm_live_ (production) or akm_test_ (testing). An invalid prefix throws a RakomiError at construction time.

API surface

Method	Description	Reference
ca.verifyToken(token)	Verify JWT access token	verifyToken()
ca.verifyWebhook(body, headers)	Verify webhook signature	verifyWebhook()
ca.middleware(options?)	Express-compatible middleware	Middleware

Requirements

• Node.js 22+ — required for jose ^6 CryptoKey native support
• ESM support — the SDK ships ESM-first