Issue, manage, and revoke gift cards programmatically. This guide walks you through authentication, your first API call, and verifying a successful response — from zero to live in minutes.
Security Notice
Keep your API key secret — never expose it in client-side code. All requests must originate from your server. If a key is compromised, revoke it immediately from the dashboard and issue a replacement.
01
Create Your Account
Dashboard
Sign up at the blackhawnketnork dashboard. You'll need a verified business email and a brief description of your integration use case. Account approval takes under 5 minutes for standard plans.
02
Generate Your First API Key
API Keys
Navigate to Settings → API Keys in your dashboard. Click "Generate New Key", assign it a label (e.g., "production-v1"), and select the required permission scopes. Copy the key immediately — it won't be shown again.
bash
// Example key format
BHKN_LIVE_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
// Store it securely in your environment
export BLACKHAWNK_API_KEY="BHKN_LIVE_sk_..."
03
Make Your First POST /v2/gift-cards Call
POST Request
Issue a gift card by sending a POST request with your card parameters. Set the Authorization header with your Bearer token, specify the currency, amount, and optional metadata.
A successful call returns HTTP 201 with a JSON payload containing the card ID, redemption code, and status. Use the card_id for all subsequent lookups, updates, or revocations.
Create scoped keys, enforce spend caps and rate limits, rotate credentials without downtime, and trace every action through an immutable audit log — all through the blackhawnketnork API or dashboard.
Key Scopes & Permissions
Scope
HTTP Methods
Endpoints Granted
Description
Risk Level
issue
POST
/v1/cards, /v1/cards/batch
Create single or batch gift cards, set denominations, expiry, and metadata.
High
read
GET
/v1/cards/:id, /v1/cards, /v1/balance
Retrieve card details, balances, and transaction history. Read-only access.
Low
redeem
POST
/v1/cards/:id/redeem, /v1/cards/:id/void
Apply redemptions, partial redemptions, and void unused card balances.
High
webhooks
ALL
/v1/webhooks, /v1/webhooks/:id
Register and manage webhook endpoints for real-time event delivery.
Medium
audit
GET
/v1/audit-logs, /v1/audit-logs/:id
Access immutable audit logs for compliance and security reviews.
Low
API keys are the primary credential for authenticating with the blackhawnketnork API. Each key is scoped to one or more permissions — issue, read, or redeem — and is tied to a single environment (sandbox or production). Principle of least privilege applies: grant only the scopes your integration actually needs.
POST /v1/api-keys
// Request{"name": "prod-checkout-service","scopes": ["issue", "read"],"environment": "production","expires_at": "2025-12-31T23:59:59Z"}// Response — key is shown ONCE, store it securely{"id": "key_01HZ9...","secret": "bhk_live_a7f3c...", // not stored by us"scopes": ["issue", "read"],"created_at": "2024-07-15T10:30:00Z"}
Security notice: The full key secret (bhk_live_...) is returned only once at creation and never stored by blackhawnketnork. Save it immediately in a secrets manager (e.g. AWS Secrets Manager, HashiCorp Vault).
All key management endpoints require a management token — a separate, non-scoped credential issued only to dashboard admins.