SDKs Overview - KnoxCall Docs

KnoxCall ships first-party SDKs for five server languages, a Terraform provider, and browser Elements packages. The five core SDKs implement the same behavioral standard, adapted to each language’s idiom — switching languages (or running a polyglot stack) never changes semantics.

Language support

Package	Runtime	Surface
`@knoxcall/sdk`	Node.js ≥ 18, TypeScript-first	Full management + data plane
`knoxcall`	Python ≥ 3.10, sync and async	Full management + data plane
`knoxcall-go`	Go, stdlib only (zero dependencies)	Full management + data plane
`knoxcall/knoxcall-php`	PHP ≥ 8.1, `ext-curl` + `ext-json` only	Full management + data plane
`knoxcall`	Ruby ≥ 3.1, stdlib only	Full management + data plane
`terraform-provider-knoxcall`	Terraform (Plugin Framework)	Routes, secrets, clients, webhooks as code
`@knoxcall/browser` + `@knoxcall/react`	Any modern browser / React ≥ 18	Client-side sealing + iframe Elements

The SDK packages are not yet published to npm, PyPI, Packagist, or RubyGems. Until they are, install from the KnoxCall monorepo by path or git — each language page shows the exact command. The code and APIs on these pages are final; only the registry publish is pending.

What every SDK guarantees

The core SDKs are held to a single parity spec (sdk/PARITY.md in the monorepo), with test coverage required for each behavior:

Automatic retries — HTTP 408, 429, 500, 502, 503, 504 retried with exponential half-jitter backoff; Retry-After honored on 429 (capped at 30s); 409 is never retried (a real conflict does not resolve by replaying).
Idempotency by default — every mutating request carries a ULID X-Idempotency-Key generated once per logical request and stable across retries, so replays are safe.
Transparent 401 re-mint — a 401 purges the cached token and retries once with fresh credentials before surfacing an error. Long-lived processes never wedge on a revoked or rotated token.
Token lifecycle — tokens cached per tenant + scope with single-flight refresh, refresh-ahead, and a stale-but-valid fallback when the token endpoint is briefly unreachable.
DPoP sender-constrained tokens (RFC 9449) — every SDK auto-upgrades to DPoP when the OAuth client requires it (dpop: "auto", the default) and supports "always": the SDK generates an ES256 keypair, binds the access token via cnf.jkt, and signs a fresh proof per request.
Shared CLI login — every SDK auto-detects the credentials file written by knoxcall login (~/.knoxcall/credentials.json), with cross-process-safe rotation of the single-use refresh token. Sign in once; every language picks it up.
Secret redaction — client secrets, access tokens, and OIDC subject tokens never appear in debug output, logs, or error messages.
Typed errors with request IDs — 401/403/404/409/422/429/5xx each map to a named error type carrying the server’s request_id (quote it when contacting support).
Envelope + pagination — the server wraps JSON responses in {data, meta}. Single-object methods return data unwrapped; paginated lists take page / per_page (default 20, cap 100) and return {data: [...], meta: {total, page, per_page, total_pages, request_id}}, with an iterator that walks every page for you.
Raw data plane — proxy calls (call() / bound routes / ephemeral()) return the raw HTTP response and never raise on the upstream’s status; legacy tk_… / AKE… keys automatically travel as x-knoxcall-key. Mutating data-plane requests are never replayed after they may have reached the wire.
Webhook constructEvent — verify the delivery’s HMAC-SHA256 signature and parse it into a typed event in one step, across all six signature formats (legacy, stripe, github, slack, aws-sns, custom), with constant-time comparison and replay protection.
Sandbox mode — a sandbox constructor option targets the isolated Test environment (sandbox.knoxcall.com management host, sandbox-{tenant}.knoxcall.com proxy host) with a tk_test_ key.
Credential-less signup() — create an account headlessly with no constructed client (see AI agent onboarding).

Authentication quickstart

Every SDK resolves credentials the same way: explicit constructor options beat environment variables, and conflicting options fail at construction. On a developer machine, log in once with the CLI below and skip configuration entirely. For servers and CI, register an OAuth client (dashboard → Settings → Security → OAuth Clients), set the environment once, and construct with zero arguments:

# OAuth client-credentials grant (recommended for servers)
export KNOXCALL_CLIENT_ID="tk_xxxxxxxx"
export KNOXCALL_CLIENT_SECRET="..."

import { KnoxCall } from "@knoxcall/sdk";

const client = new KnoxCall(); // credentials from `knoxcall login` or the environment

from knoxcall import KnoxCall

client = KnoxCall()  # credentials from `knoxcall login` or the environment

import "github.com/knoxcall/knoxcall-go/knoxcall"

client, err := knoxcall.New(knoxcall.Options{}) // credentials from `knoxcall login` or the environment

use KnoxCall\KnoxCall;

$client = new KnoxCall(); // credentials from `knoxcall login` or the environment

require "knoxcall"

client = KnoxCall::Client.new # credentials from `knoxcall login` or the environment

You do not need to configure a tenant: management calls resolve it server-side from the credential, and the data-plane hostname is auto-discovered on first proxy call. Passing tenant (or setting KNOXCALL_TENANT) just skips the discovery lookup.

Legacy API keys still work everywhere: set KNOXCALL_API_KEY to a long-lived key (tk_live_…, tk_test_…, AKE…) or a pre-acquired kc_… token instead of the client-credentials pair — or pass it to the constructor as apiKey / api_key. A pre-acquired key is sent as-is and never auto-renewed. Prefer knoxcall login or an OAuth client for new integrations — see Authentication.

Log in once with the CLI

On a developer machine, skip credentials entirely. Every KnoxCall SDK package ships the knoxcall command via its own package manager (pip, npm, gem, Composer, go install) — same surface, same credentials file, so it doesn’t matter which one you install. Sign in once in your browser (authorization code + PKCE) and every script, notebook, and agent on the machine — in any of the five languages — picks the credential up automatically. No env vars, no keys in code:

pip install knoxcall              # or: npm i -g @knoxcall/sdk / gem install knoxcall /
                                  #     composer global require knoxcall/knoxcall-php /
                                  #     go install github.com/knoxcall/knoxcall-go/cmd/knoxcall@latest
knoxcall login                    # opens your browser (PKCE); prints the URL too
knoxcall login --device           # headless/SSH machines: device-code flow (RFC 8628)
knoxcall login --sandbox          # log in against the sandbox environment
knoxcall login --profile staging  # keep multiple accounts side by side
knoxcall whoami                   # show the signed-in tenant
knoxcall logout                   # revoke + remove the stored credential

After that, the zero-argument constructors above just work: credentials land in ~/.knoxcall/credentials.json (file mode 0600), and the stored tenant and base URL seed the client automatically — explicit constructor options and env vars always win. Access tokens refresh themselves, and refreshes are cross-process safe (file lock + atomic rotation of the single-use refresh token). If a refresh fails because the credential was revoked or expired, the SDK raises its typed authentication error telling you to run knoxcall login again. Override the file path with KNOXCALL_CREDENTIALS_FILE; select a non-default profile with KNOXCALL_PROFILE.

Credential resolution order

With no explicit constructor credentials, every SDK resolves from the environment in priority order:

KNOXCALL_ACCESS_TOKEN (or KNOXCALL_API_KEY) — a pre-acquired token
The credentials file written by knoxcall login (~/.knoxcall/credentials.json)
Workload identity auto-detect — Node.js and Python only (GitHub Actions, GCP, AWS IRSA, Azure Managed Identity, Vercel, and other CI OIDC issuers); zero stored secrets in CI
KNOXCALL_CLIENT_ID + KNOXCALL_CLIENT_SECRET — client-credentials grant

Canonical environment variables

Variable	Meaning
`KNOXCALL_CLIENT_ID` / `KNOXCALL_CLIENT_SECRET`	OAuth client-credentials grant
`KNOXCALL_API_KEY`	pre-acquired key or token (`KNOXCALL_ACCESS_TOKEN` is an equivalent spelling and wins when both are set)
`KNOXCALL_TENANT`	tenant slug (optional — auto-discovered when unset)
`KNOXCALL_ENVIRONMENT`	default environment for data-plane calls
`KNOXCALL_BASE_URL`	management API base override
`KNOXCALL_PROXY_BASE_URL`	data-plane base override
`KNOXCALL_CREDENTIALS_FILE`	credentials-file path override (default `~/.knoxcall/credentials.json`)
`KNOXCALL_PROFILE`	credentials-file profile to use (default `default`)

Pick your language

Node.js / TypeScript

@knoxcall/sdk — fully typed, DPoP, workload identity, token stores

Python

knoxcall — one import, sync or async, thread- and fork-safe

Go

knoxcall-go — stdlib only, context-first, goroutine-safe

PHP

knoxcall/knoxcall-php — PHP-FPM aware token handling

Ruby

knoxcall gem — Mutex-safe for Puma and Sidekiq

Terraform

Routes, secrets, clients, and webhooks as code

Browser Elements

Seal PANs and PII in the page; reveal with single-use capability tokens

​Language support

​What every SDK guarantees

​Authentication quickstart

​Log in once with the CLI

​Credential resolution order

​Canonical environment variables

​Pick your language

Node.js / TypeScript

Python

Go

PHP

Ruby

Terraform

Browser Elements

Language support

What every SDK guarantees

Authentication quickstart

Log in once with the CLI

Credential resolution order

Canonical environment variables

Pick your language