Quickstart
Get Holdify running in 5 minutes.
Create an account
Sign up at app.holdify.io to create your account. You will get a project API key that you will use to authenticate with the Holdify API.
Create accountConnect your payment provider
Go to Settings → Integrations in the Holdify dashboard. This syncs your subscriptions so entitlements are automatically updated when customers subscribe, upgrade, or cancel.
Install the SDK
Install the @holdify/sdk package in your project.
npm install @holdify/sdk
# or
pnpm add @holdify/sdk
# or
yarn add @holdify/sdkAdd your project API key to your environment variables:
# .env
HOLDIFY_PROJECT_KEY=hpk_live_your_project_keyAdd middleware to your API
Choose your framework and add budget protection in one line. The middleware automatically verifies API keys and enforces budget limits.
"text-gray-500">// middleware.ts
import { withHoldify } from '@holdify/nextjs';
"text-gray-500">// Budget protection in one line
export default withHoldify();
export const config = {
matcher: '/api/:path*',
};Manual verification (optional)
For more control, you can use the SDK directly to verify API keys. The verify method returns the key's validity, remaining budget, and entitlements.
import { Holdify } from '@holdify/sdk';
const holdify = new Holdify({
apiKey: process.env.HOLDIFY_PROJECT_KEY,
});
// In your API route
export async function handleRequest(req: Request) {
const apiKey = req.headers.get('x-api-key');
const result = await holdify.verify(apiKey, {
resource: 'api-calls',
units: 1,
});
if (!result.valid) {
return new Response('Invalid API key', { status: 401 });
}
if (result.rateLimit.remaining <= 0) {
return new Response('Rate limit exceeded', { status: 429 });
}
if (result.quota.remaining <= 0) {
return new Response('Monthly quota exceeded', { status: 402 });
}
// Process the request...
return new Response('Success');
}Response shape
The verify method returns the following fields:
{
valid: boolean; // Is the key valid?
rateLimit: {
remaining: number; // Requests remaining this minute
limit: number; // Max requests per minute
reset: number; // Unix timestamp when window resets
};
quota: {
remaining: number; // Quota remaining this month
limit: number; // Total monthly quota
resetAt: string; // ISO 8601 timestamp when quota resets
};
plan: string | null; // Customer's plan (e.g., "pro")
features: string[]; // Feature flags for gating
metadata: object; // Custom metadata
}Next steps
You are all set!
Make sure you have completed these steps:
- Created a Holdify account
- Connected your payment provider
- Installed the SDK
- Added middleware to your API