[ DEVELOPER INTEGRATION GUIDE ]

API Reference

The Haxnation API allows organizations and developers to integrate event discovery, attendee eligibility verification, and dynamic certificate generation into third-party portals, LMS platforms, or custom web apps.

Standardized Base URL

All API requests must be sent over HTTPS to our primary API domain:

https://api.haxnation.org
Events API Prefix

/events/api/events

Events, attendee eligibility, and event-based certificate issuance.

B2B Certificate Prefix

/events/api/v1

Headless custom template rendering with credit deduction.

Authentication & API Key Types

ALL THIRD-PARTY REQUESTS REQUIRE AUTHENTICATION VIA API KEY

All incoming requests from external domains or backend servers must include your API Key in the X-API-KEY header.

API Key Types & Permissions

PUBLIC KEY Client-Side Safe

Designed for frontend browser applications, SPAs, and public integration widgets. Restricted strictly to read-only operations (such as listing public events, retrieving event details, checking email eligibility, and verifying certificates).

Security: Enforces Allowed Domains origin whitelisting to block unauthorized cross-site domain access.
PRIVATE KEY Server-Side Only

Designed exclusively for confidential server-to-server backend integrations. Grants access to all endpoints, including high-privilege operations like attendee certificate issuance and B2B template rendering with credit deduction.

Security: Must NEVER be exposed in frontend client JavaScript, mobile apps, or public repositories.
Endpoint API Key Compatibility Matrix
Endpoint Method Path Supported Key Usage Context
List Events GET /events/api/events PUBLIC PRIVATE Client widget or backend
Get Event Details GET /events/api/events/{id} PUBLIC PRIVATE Client widget or backend
Check Eligibility GET /events/api/events/eligibility PUBLIC PRIVATE Frontend lookup widgets
Event Cert by Email POST /events/api/events/{id}/certificate-by-email PRIVATE ONLY Backend server only
Event Cert Download (credits) POST /events/api/events/{id}/certificate/download PUBLIC PRIVATE Same route for site + third parties (1 credit/cert, idempotent)
B2B Template Cert POST /events/api/v1/certificates/generate PRIVATE ONLY Backend server only (1 credit/cert)
Verify Certificate GET /events/api/events/certificate/verify/{certId} PUBLIC PRIVATE Public verification page or backend
Redirect to Cert GET /events/api/events/certificate/redirect/{certId} PUBLIC PRIVATE QR code scan & browser redirect

Required Request Headers

For GET requests:

X-API-KEY: HAX_abcdef1234567890abcdef...

For POST / PUT requests:

X-API-KEY: HAX_abcdef1234567890abcdef... Content-Type: application/json x-amz-content-sha256: <SHA256_HEX_HASH_OF_REQUEST_BODY>

Important Note on POST Requests

When making POST requests from your backend server, compute the SHA256 hex digest of the raw JSON body and include it in the x-amz-content-sha256 header to satisfy API Gateway edge validation.

List Events

Retrieves public events hosted by the community associated with your API Key.

GET https://api.haxnation.org/events/api/events
PUBLIC PRIVATE
Supported Keys: PUBLIC or PRIVATE (Read-only; safe for client frontend widgets or backend servers)

Example cURL

curl -X GET "https://api.haxnation.org/events/api/events" \ -H "X-API-KEY: HAX_your_public_or_private_key"

Response (200 OK)

{ "success": true, "data": [ { "id": "e_abc12345", "name": "CyberSecurity Summit 2026", "date": "2026-10-24T10:00:00Z", "location": "Online / Virtual", "status": "ACTIVE", "eventType": "FULL" } ] }

Get Event Details

Retrieves metadata, scheduling, and registration configuration for a specific event by ID or custom URL slug.

GET https://api.haxnation.org/events/api/events/{id}
PUBLIC PRIVATE
Supported Keys: PUBLIC or PRIVATE (Read-only; safe for client frontend widgets or backend servers)

Path Parameters

Parameter Type Description
id REQ string The unique Event ID (UUID) or custom slug.

Response (200 OK)

{ "success": true, "data": { "id": "e_abc12345", "name": "CyberSecurity Summit 2026", "description": "Annual flagship security summit.", "date": "2026-10-24T10:00:00Z", "location": "Auditorium 1", "settings": { "isCertificateOnly": false, "requiresApproval": false } } }

Check Attendee Eligibility

Checks an attendee's email address against the community's events to find which certificates they are eligible to claim or download. Ideal for client-side search widgets.

GET https://api.haxnation.org/events/api/events/eligibility?email={email}
PUBLIC PRIVATE
Supported Keys: PUBLIC or PRIVATE (Read-only; ideal for client-side widgets with Allowed Domains configured)

Query Parameters

Parameter Type Description
email REQ string The attendee's registered email address (URL encoded).

Example cURL

curl -X GET "https://api.haxnation.org/events/api/events/eligibility?email=attendee%40example.com" \ -H "X-API-KEY: HAX_your_public_or_private_key"

Response (200 OK)

{ "success": true, "data": [ { "PK": "EVENT#e_abc12345", "name": "CyberSecurity Summit 2026", "date": "2026-10-24T10:00:00Z", "userRegistration": { "status": "APPROVED", "certificateIssuedAt": "2026-10-24T18:30:00Z" } } ] }

Generate Event Certificate by Email

Issues or retrieves the generated certificate for a registered attendee by Event ID and email address. Generates official certificates valid for 2 years.

Validity & Retention Policy

All certificates generated on Haxnation are valid and stored for 2 years from date of issuance.

POST https://api.haxnation.org/events/api/events/{id}/certificate-by-email
PRIVATE KEY ONLY
Key Requirement: PRIVATE KEY ONLY (Server-to-server calls only. Public keys will receive HTTP 401 Unauthorized)

Request Body

{ "email": "[email protected]", "name": "Jane Doe" // Optional override for certificate display }

Node.js Server Implementation

const crypto = require('crypto'); const fetch = require('node-fetch'); async function issueCertificate(eventId, email, name) { const payload = JSON.stringify({ email, name }); const hash = crypto.createHash('sha256').update(payload).digest('hex'); const response = await fetch(`https://api.haxnation.org/events/api/events/${eventId}/certificate-by-email`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-API-KEY': process.env.HAXNATION_PRIVATE_KEY, // Use your PRIVATE key here 'x-amz-content-sha256': hash }, body: payload }); return await response.json(); }

Response (200 OK)

{ "success": true, "data": { "certId": "c_9f8e7d6c5b4a", "eventName": "CyberSecurity Summit 2026", "userName": "Jane Doe", "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...", "issuedAt": "2026-10-24T18:30:00Z", "expiresAt": "2028-10-24T18:30:00Z", "validity": "2 years from date of issue" } }

B2B Headless Template Certificate

Renders a high-resolution certificate based on your community's active default template using dynamic variable substitution. Deducts 1 credit from your account per generation. Generated certificates are valid and stored for 2 years from date of issue.

POST https://api.haxnation.org/events/api/v1/certificates/generate
PRIVATE KEY ONLY
Key Requirement: PRIVATE KEY ONLY (Server-to-server calls only. Public keys will receive HTTP 403 Forbidden)

Request Body

Pass template variables in the data map matching the placeholder keys configured in your certificate designer:

{ "data": { "name": "Jane Doe", "course": "Advanced Threat Intelligence", "date": "October 24, 2026", "rank": "1st Place" } }

Example cURL

curl -X POST "https://api.haxnation.org/events/api/v1/certificates/generate" \ -H "Content-Type: application/json" \ -H "X-API-KEY: HAX_your_private_key_here" \ -H "x-amz-content-sha256: <SHA256_HEX_HASH>" \ -d '{"data": {"name": "Jane Doe", "course": "Threat Intelligence"}}'

Deduction is idempotent: send Idempotency-Key (or idempotencyKey in the body) to make retries safe — replays never deduct twice. Without one, identical payloads from the same key collapse into a single deduction.

Response (200 OK)

{ "success": true, "data": { "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...", "issuedAt": "2026-10-24T18:30:00Z", "expiresAt": "2028-10-24T18:30:00Z", "validity": "2 years from date of issue", "creditsRemaining": 42 } }

Event Certificate Download (Pay with Credits)

Settles a paid event certificate with 1 community credit instead of a fiat payment order, on the existing download endpoint — no new path, same enforcement for the main site and third parties. Prerequisites: the event opts in via certificateSettings.allowCredits=true, the community account holds credits, and the caller's API key belongs to the event's community. Already-issued certificates return the existing certificate without charging.

POST https://api.haxnation.org/events/api/events/{id}/certificate/download
PUBLIC PRIVATE
Supported Keys: PUBLIC or PRIVATE (main site uses its own PUBLIC key; key must belong to the event's community)

Request Body

{ "payWithCredits": true, "idempotencyKey": "evt-livedemo-u_123-01" }

Send either orderId (fiat) or payWithCredits — sending both returns HTTP 400. Pass the key via the Idempotency-Key header or the idempotencyKey field; when omitted it defaults to credits-{eventId}-{userId}.

Example cURL

curl -X POST "https://api.haxnation.org/events/api/events/evt_abc123/certificate/download" \ -H "Content-Type: application/json" \ -H "X-API-KEY: HAX_site_public_key" \ -H "Idempotency-Key: evt-livedemo-u_123-01" \ -H "x-amz-content-sha256: <SHA256_HEX_HASH>" \ -d '{"payWithCredits": true}'

Idempotency (no double-deduct)

Retrying with the same key never deducts twice: a completed key replays the stored transactionId (CREDITS_<key>), a concurrent duplicate returns HTTP 409, an empty balance returns HTTP 402 and generation failures auto-refund the credit.

Response (200 OK)

{ "success": true, "data": { "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...", "certId": "9f3a...", "transactionId": "CREDITS_evt-livedemo-u_123-01", "issuedAt": "2026-10-24T18:30:00Z", "expiresAt": "2028-10-24T18:30:00Z", "validity": "2 years from date of issue" } }

Verify Certificate

Validates the authenticity and issuance metadata of any certificate issued by Haxnation using its unique Certificate ID or hash. Certificates are valid for 2 years from date of issue; expired certificates return HTTP 403 Forbidden.

GET https://api.haxnation.org/events/api/events/certificate/verify/{certId}
PUBLIC PRIVATE
Supported Keys: PUBLIC or PRIVATE (Public verification; callable from browser verification tools or backend systems)

Response (200 OK)

{ "success": true, "data": { "message": "Certificate Verified", "owner": "Jane Doe", "event": "CyberSecurity Summit 2026", "eventId": "e_abc12345", "issuedAt": "2026-10-24T18:30:00Z", "expiresAt": "2028-10-24T18:30:00Z", "validity": "2 years from date of issue" } }

Redirect Certificate URL

Direct HTTP 302 redirect endpoint embedded in QR codes on certificates to route visitors directly to the certificate's public verification page.

GET https://api.haxnation.org/events/api/events/certificate/redirect/{certId}
PUBLIC PRIVATE
Supported Keys: PUBLIC or PRIVATE (Public QR destination; browser redirect)

Returns an HTTP 302 Found with a Location header directing to the live validation web interface.