Docs Authentication

Authentication

All API requests require authentication using a project API key.

The Holdify API uses Bearer token authentication. Include your project API key in the Authorization header with every request.

Authorization header

http

Authorization: Bearer <project_api_key>

Key types

Holdify uses two types of API keys:

PRJ

Project API Keys

Used to authenticate your backend with the Holdify API.

Prefix: hpk_live_ or hpk_test_

Created in the Holdify dashboard
Never expose in client-side code

API

Customer API Keys

Keys you issue to your customers. These are what you verify with Holdify.

Prefix: hk_live_ or hk_test_

Created via POST /v1/api-keys
Given to your customers

Base URL

Environment	Base URL
Production	https://api.holdify.io
Staging	https://api.staging.holdify.io

Example request

curl

bash

curl -X POST https://api.holdify.io/v1/verify \
  -H "Authorization: Bearer hpk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"key": "hk_live_customer_key"}'

Environment variables

Store your API keys in environment variables. Never commit them to version control.

.env

bash

# Production
HOLDIFY_PROJECT_KEY=hpk_live_abc123...

# Development/Staging (optional)
HOLDIFY_PROJECT_KEY_DEV=hpk_test_xyz789...

Using the SDK

The SDK handles authentication automatically when you pass your API key:

SDK initialization

typescript

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

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

Security best practices

Never expose project keys in client-side code. Only use them in server-side code, edge functions, or backend services.
Use environment variables. Don't hardcode API keys in your source code.
Rotate keys regularly. Use the dashboard to rotate project keys if compromised.
Use separate keys per environment. Use test keys for development and live keys for production.

Rate limits

API rate limits are based on your plan. When you exceed the limit, you'll receive a 429 response with rate limit headers:

Header	Description
X-RateLimit-Limit	Maximum requests per window
X-RateLimit-Remaining	Requests remaining in window
X-RateLimit-Reset	Unix timestamp when window resets
Retry-After	Seconds to wait before retrying (on 429)