SDKs

Three repositories hold the official SDKs: a Go client, a Python client, and a TypeScript monorepo that publishes two packages under the @kaitencloud scope — a server client and a browser client. Each repository holds its own installation and usage instructions, kept next to the code they describe. This page tells you which one to open, what it covers, and where the line between browser and server runs.

Three repositories

Built on the specification

The API publishes its own OpenAPI specification at /api/openapi.json, and that specification is generated from the API's code — not written by hand. Every SDK is built on that document, each in its own way, so the four do not expose one identical surface. The table states what each one is and what it reaches; it describes sdk-go v0.1.0, kaitencloud 1.0.0, @kaitencloud/client 1.1.0 and @kaitencloud/server 1.0.1.

Webhook verification is a Kaiten Cloud concern, since managed delivery is a Kaiten Cloud capability. A React SDK, with embedded components for gating, pricing and the customer portal, is on the roadmap Coming soon.

Each server-side SDK makes a refused usage report explicit, so the 409 the API answers never reads as a success: Instances.ReportUsage returns sdk.ErrThresholdExceeded in Go, instances.report_usage raises ThresholdExceededError in Python, and @kaitencloud/server throws a KaitenError that isThresholdExceeded(error) recognises.

A first call

One read against the Kaiten Sushi Shop dataset, in each server-side SDK. The base URL keeps its /api prefix: https://app.kaiten.sh/api on Kaiten Cloud, http://localhost:6060/api on the Community Edition. The Go client, @kaitencloud/client, and the OpenFeature providers need it in the value; the Python client and @kaitencloud/server add it when it is missing. Installing each SDK is covered by its repository's README.

package main

import (
    "context"
    "fmt"
    "log"

    sdk "github.com/kaitencloud/sdk-go"
)

func main() {
    client, err := sdk.NewClient("http://localhost:6060/api", sdk.WithBearerToken("ksh_xxx"))
    if err != nil {
        log.Fatal(err)
    }

    customer, err := client.Customers.Get(context.Background(), "sakura-tokyo")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(customer.Name) // Sakura Tokyo
}

from kaitencloud import KaitenClient

client = KaitenClient(base_url="http://localhost:6060/api", token="ksh_xxx")

customer = client.customers.get("sakura-tokyo")
print(customer.name)  # Sakura Tokyo

import { createKaitenClient, Customers } from '@kaitencloud/server';

const client = createKaitenClient({
  baseUrl: 'http://localhost:6060/api',
  token: 'ksh_xxx',
});

const { data: customer } = await Customers.getCustomer({
  client,
  path: { customerSlug: 'sakura-tokyo' },
});
console.log(customer?.name); // Sakura Tokyo

Credentials

Every server-side SDK authenticates with a service-account token (ksh_…), sent as Bearer — see authentication for issuing one and scopes for what to grant it. The call above needs read:customers.

The Go and Python SDKs each carry a second client for the Platform API and its credential (ksm_…). That surface belongs to the operator of a self-hosted stack: it listens on its own port and is not reachable on Kaiten Cloud. The TypeScript packages do not model it — a token that reaches every organization has no place in an application bundle.

Browser and server: one boundary

The split between client and server is a security boundary made structural. In a browser, @kaitencloud/client never holds a secret, so it is the package a browser bundle imports; on a server, the same client may carry a ksh_ token. @kaitencloud/server carries the full contract behind a ksh_ token and never ships to a browser. In @kaitencloud/client, the transport adds a runtime check: a request that would carry a ksh_ or ksm_ credential out of a browser is refused before it leaves. That check catches a developer's mistake — it is not a security boundary in itself. A secret that has reached a browser is already public and must be revoked.

How @kaitencloud/client sends its credential is its authScheme option. It is required and has no default: a KaitenClient built without one throws.

• "bearer" — the credential goes out as Authorization: Bearer. It is a ksh_… token, or a JWT from the identity provider the API's gateway trusts; both carry rights over the whole organization, so this scheme belongs on a server.
• "none" — no credential. For an endpoint in front of Kaiten that authenticates the request itself, such as a route of your own backend.
• "publishable" Coming soon — a publishable key (pk_…), the credential designed for the browser. The SDK carries the scheme, and no endpoint accepts it yet.

A credential scoped to one of your customers, for that customer's browser, is on the roadmap too Coming soon. Until one ships, a browser holds no Kaiten credential: your backend reads the License catalog or a customer's snapshot — with @kaitencloud/client and authScheme: "bearer", or the operations underneath with @kaitencloud/server — and hands the page plain data. The ksh_ token stays on the server.

Flag evaluation: OpenFeature

Feature flags need no Kaiten-specific client. Kaiten implements the OpenFeature Remote Evaluation Protocol (OFREP), so any OpenFeature SDK configured with the generic OFREP provider evaluates Kaiten flags — base URL plus the caller's credential. The generic providers cover each runtime: @openfeature/ofrep-web-provider in a browser, @openfeature/ofrep-provider in Node, openfeature-provider-ofrep in Python, and the ofrep provider of go-sdk-contrib in Go. Kaiten's own console evaluates its platform flags through the web provider. The OpenFeature & OFREP page covers the endpoints, the context they expect, and provider configuration in Go, Python, and JavaScript.

Where to go next