SDK, REST, CLI, and MCP

OfferKit defines its contract once and exposes it through several interfaces. They share the same resources and business behavior. API-key clients and hosted OAuth clients have different credentials and permission controls; choose based on where the caller runs and how it should be operated.

TypeScript SDK

Use the SDK in a trusted TypeScript server:

pnpm add @offerkit/sdk

import { createClient, verifyWebhook } from "@offerkit/sdk";

export const offerkit = createClient({
  baseUrl: process.env.OFFERKIT_API_URL!,
  apiKey: process.env.OFFERKIT_API_KEY!,
});

Types flow from the oRPC contract without a code-generation step. The client is safe for edge runtimes; verifyWebhook uses Node crypto only when that helper is imported and used.

The SDK follows nested resource paths, but input shape depends on the route:

await offerkit.vouchers.validate({
  params: { code: "WELCOME10" },
  body: { order: { amount: 5000, currency: "USD", items: [] } },
});

await offerkit.campaigns.update({
  params: { id: campaignId },
  body: { patch: { status: "active" } },
});

await offerkit.referrals.listCodes({
  params: { programId },
  query: { limit: 20 },
});

Update shapes are not universal. Voucher, campaign, order, and program updates use body.patch. Workspace updates have direct fields because they have no path parameters. Use installed SDK types or the server’s OpenAPI to check the particular operation.

REST API

Use REST from any backend language. Send:

Authorization: Bearer <api-key>
Content-Type: application/json

Routes are served under /api/v1. The current deployment exposes an OpenAPI 3.1 document at /api/openapi.json, which is the authoritative route and schema inventory for that running version.

CLI

Use the CLI for operator scripts, diagnostics, and back-office work:

pnpm add -g @offerkit/cli
offerkit login --url https://offerkit.example.com --api-key offerkit_…

offerkit vouchers list
offerkit vouchers validate WELCOME10 --amount 5000 --currency USD
offerkit vouchers redeem WELCOME10 --amount 5000 --currency USD --idempotency-key order-42
offerkit customers list --search alice

CLI amounts use minor units: 5000 USD is USD 50.00. Percentage inputs use basis points, so 1000 is 10%.

Login writes ~/.offerkitrc with mode 0600. OFFERKIT_API_URL and OFFERKIT_API_KEY environment variables override file configuration. Avoid placing a production key in shared shell history or CI logs.

MCP server

For a hosted deployment, enable the OAuth-protected Streamable HTTP endpoint:

OFFERKIT_MCP_ENABLED=true
OFFERKIT_PUBLIC_URL=https://offerkit.example.com

The canonical endpoint is https://offerkit.example.com/mcp. Configure Codex with:

codex mcp add offerkit --url https://offerkit.example.com/mcp
codex mcp login offerkit

Configure Claude Code with the following command, then run /mcp and complete the browser sign-in:

claude mcp add --transport http offerkit https://offerkit.example.com/mcp

The OAuth grant uses the signed-in OfferKit user’s role and can be revoked under Settings → Agent connections.

For a local stdio process using an API key, configure the published package instead:

{
  "mcpServers": {
    "offerkit": {
      "command": "npx",
      "args": ["-y", "@offerkit/mcp"],
      "env": {
        "OFFERKIT_API_URL": "https://offerkit.example.com",
        "OFFERKIT_API_KEY": "offerkit_…"
      }
    }
  }
}

Tool names follow SDK paths with underscores, such as vouchers_validate and referrals_convert. Contract metadata marks tools as safe, mutating, or destructive and adds confirmation guidance to state-changing operations.

Grant a local MCP process a scoped key appropriate for the intended agent tasks. Risk labels help a host present confirmation; they do not replace API authorization.

Which one should I use?

Do not call the SDK or REST API directly from an untrusted browser or mobile client.