SDKs Overview

​

Language support

​

What every SDK guarantees

• 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

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

# — or — a single pre-acquired key/token (kc_…, tk_…, or AKE…)
export KNOXCALL_API_KEY="tk_live_..."

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

const client = new KnoxCall(); // credentials from the environment

from knoxcall import KnoxCall

client = KnoxCall()  # credentials from the environment

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

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

use KnoxCall\KnoxCall;

$client = new KnoxCall(); // credentials from the environment

require "knoxcall"

client = KnoxCall::Client.new # credentials from the environment

​

Log in once with the CLI

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

​

Credential resolution order

1. KNOXCALL_ACCESS_TOKEN (or KNOXCALL_API_KEY) — a pre-acquired token
2. The credentials file written by knoxcall login (~/.knoxcall/credentials.json)
3. 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
4. KNOXCALL_CLIENT_ID + KNOXCALL_CLIENT_SECRET — client-credentials grant

​

Canonical environment variables

​

Pick your language