Integration guides
Use Organization API Version 1 from your server
Start with an approved domain and complete keys, then use safe reads before private HMAC-signed operations.
Before you start
- An approved Organization account, verified HTTPS domain and complete Public/Private keys copied from Creator settings.
- A trusted Node 20+ server for the workspace-local TypeScript SDK, or Python/PHP HTTPS code on your backend.
- The Version 1 reference and required capabilities; API version 1 differs from private signature version 2.
Configure complete keys and perform a safe read
Keep SPARKGLIM_APPROVED_DOMAIN and complete keyId:secret values in server-only configuration. Public reads send x-white-label-domain and the complete public or campaign key. Do not invent another separately configured key ID.
The TypeScript example assumes the existing @sparkglim/organization-sdk workspace package is built and available to your app. Public npm publication is unverified. Python and PHP call the actual HTTPS read without claiming dedicated SDKs.
import { SparkGlimOrganization } from '@sparkglim/organization-sdk';
const client = new SparkGlimOrganization({
baseUrl: 'https://api.sparkglim.net',
domain: process.env.SPARKGLIM_APPROVED_DOMAIN!,
publicKey: process.env.SPARKGLIM_PUBLIC_KEY,
privateKey: process.env.SPARKGLIM_PRIVATE_KEY,
campaignKey: process.env.SPARKGLIM_CAMPAIGN_KEY,
});
export async function readOrganizationCampaigns() {
return client.campaigns.list();
}import json
import os
import urllib.request
def read_organization_campaigns():
key = os.environ["SPARKGLIM_PUBLIC_KEY"]
domain = os.environ["SPARKGLIM_APPROVED_DOMAIN"]
request = urllib.request.Request("https://api.sparkglim.net/api/white-label/v1/campaigns", headers={"Accept":"application/json", "x-white-label-domain":domain, "x-white-label-key":key})
with urllib.request.urlopen(request, timeout=15) as response:
payload = json.load(response)
if payload.get("success") is not True:
raise RuntimeError("Organization read failed")
return payload.get("data")<?php
function read_organization_campaigns(): array {
$handle = curl_init('https://api.sparkglim.net/api/white-label/v1/campaigns');
curl_setopt_array($handle, [CURLOPT_RETURNTRANSFER=>true, CURLOPT_TIMEOUT=>15, CURLOPT_HTTPHEADER=>[
'Accept: application/json', 'x-white-label-domain: '.getenv('SPARKGLIM_APPROVED_DOMAIN'), 'x-white-label-key: '.getenv('SPARKGLIM_PUBLIC_KEY')
]]);
$raw = curl_exec($handle);
$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
curl_close($handle);
if ($raw === false || $status < 200 || $status >= 300) throw new RuntimeException('Organization read failed');
$payload = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if (($payload['success'] ?? false) !== true) throw new RuntimeException('Organization read failed');
return $payload['data'];
}Understand private signing before mutation
Private requests require domain-bound HMAC signature version 2, timestamp, fresh nonce, scope/capabilities and operation-specific idempotency. The canonical form is v2.domain.idempotencyKey.campaignKey.timestamp.nonce.METHOD.pathname.sortedQuery.sha256(rawBody). Sign actual transmitted bytes and sorted encoded query.
The workspace SDK signs its implemented methods. Never bundle this Node crypto client in a browser, reuse a nonce or copy the legacy WordPress signer as the current contract.
Use an explicit controlled checkout operation
The inert example delegates pricing and session creation to client.checkout.create. input must contain actual documented campaign/ticket/quantity/contact fields and an allowed relative return_path; it is not an arbitrary priced order.
Use a stable idempotency key for the same operation, return authorization_url to the client and navigate to central checkout. Server controls payment and fulfillment; add no browser verification or payment poller.
import { randomUUID } from 'node:crypto';
import { SparkGlimOrganization } from '@sparkglim/organization-sdk';
export async function createApprovedTestCheckout(client: SparkGlimOrganization, input: unknown, stableRequestId: string, approvedTest: boolean) {
if (!approvedTest) throw new Error('Approved test configuration required');
const data = await client.checkout.create(input, stableRequestId);
if (typeof data.authorization_url !== 'string') throw new Error('No paid checkout URL returned');
const target = new URL(data.authorization_url);
if (target.origin !== 'https://checkout.sparkglim.net' || target.username || target.password) throw new Error('Invalid checkout URL');
return { authorization_url: target.href };
}
export const newRequestId = () => randomUUID();Check your integration
- Confirm domain/key scope and keep credentials out of bundles and logs.
- Test unsigned, expired, replayed or unauthorized requests only in a controlled environment.
- Separate workspace source availability from deployed readiness and verified package publication.