Going OpenAPI-first: build your own 1Claw SDK in any language

We believe the best way to grow a developer ecosystem is to make the API the product, not the SDK. Today we're announcing two things that make that real — and opening the door for the community to build 1Claw clients in any language.

What we shipped

Two npm packages, both open:

• @1claw/openapi-spec — the canonical OpenAPI 3.1.0 specification for the entire 1Claw Vault API, published to npm. Every endpoint, every schema, every error code.
• @1claw/sdk v0.3.0 — our TypeScript SDK, now internally restructured with types generated from the spec and a new plugin architecture for community extensions.

Why OpenAPI-first?

Until now, our TypeScript SDK was hand-written. Adding a new endpoint meant updating types, methods, and tests manually. Developers using Python, Go, Rust, or Java had to reverse-engineer the API from our docs. There was no machine-readable contract a CI pipeline could validate against.

Going spec-first flips this. The OpenAPI document is the source of truth. The TypeScript SDK's types are generated from it. And any developer can feed the same spec into their favorite codegen tool to get a fully typed client — no PRs, no waiting on us.

The OpenAPI spec package

Install it with a single command:

npm install @1claw/openapi-spec

The package ships two files:

The spec covers every endpoint in the 1Claw API: authentication, vaults, secrets, agents, policies, sharing, audit, billing, chains, Intents API, MFA, and device auth.

What changed in @1claw/sdk v0.3.0

The SDK was internally restructured into four layers:

src/
├── core/        — HTTP client, error handling, auth
├── resources/   — One module per API resource
├── plugins/     — Extension interfaces
└── generated/   — Types from the OpenAPI spec

The public API surface is unchanged — import { createClient } from "@1claw/sdk" works exactly as before. But request and response types now derive from the spec via openapi-typescript:

import type { ApiSchemas } from "@1claw/sdk";

type Vault = ApiSchemas["VaultResponse"];
type Agent = ApiSchemas["AgentResponse"];

Plugin architecture

v0.3.0 also introduces three plugin interfaces that let you extend the SDK without forking it:

Implement any interface in your own npm package — no PRs to the SDK needed:

import { createClient } from "@1claw/sdk";
import type { CryptoProvider } from "@1claw/sdk";

const myKmsProvider: CryptoProvider = {
  name: "aws-kms",
  async encrypt(plaintext, keyId) { /* ... */ },
  async decrypt(ciphertext, keyId) { /* ... */ },
  async generateKey(algorithm) { /* ... */ },
};

const client = createClient({
  baseUrl: "https://api.1claw.xyz",
  apiKey: "1ck_...",
  plugins: { cryptoProvider: myKmsProvider },
});

Build your own community SDK

This is the part we're most excited about. Here's how to generate a client in your language of choice using the published spec.

Python

npx openapi-python-client generate \
  --path node_modules/@1claw/openapi-spec/openapi.json \
  --output-path ./oneclaw-python

Go

oapi-codegen -package oneclaw \
  node_modules/@1claw/openapi-spec/openapi.yaml > oneclaw.go

Rust

openapi-generator generate \
  -i node_modules/@1claw/openapi-spec/openapi.yaml \
  -g rust -o ./oneclaw-rs

Java / Kotlin

openapi-generator generate \
  -i node_modules/@1claw/openapi-spec/openapi.yaml \
  -g java -o ./oneclaw-java \
  --additional-properties=library=native

Any other language

The spec follows OpenAPI 3.1.0 strictly. Any tool that reads the standard will work:

• OpenAPI Generator — 50+ languages
• openapi-typescript — TypeScript types
• oapi-codegen — Go
• Orval — TypeScript + React Query
• Kiota — C#, Go, Java, PHP, Python, Ruby, Swift, TypeScript

Tips for community SDK authors

1. Pin a version. The spec is versioned on npm. Lock to a specific version in your dependency file or download the YAML into your repo.
2. Regenerate in CI. Add a step that pulls the latest spec and regenerates types. Catch breaking changes early.
3. Add auth helpers. The raw generated client won't know about 1ck_ API key auth or agent JWT exchange. Add a thin wrapper that handles Authorization: Bearer <token> and token refresh.
4. Test against the sandbox. Point your client at https://api.1claw.xyz with a test org to validate real request/response shapes.
5. Publish it. If you build a solid client, publish it to your language's package registry and let us know — we'll link it from our docs.

What's next

• Contract testing in CI — we're adding automated spec-vs-live-API validation to catch drift before it ships.
• Official Python SDK — a first-party pip install 1claw package is in progress, generated from the same spec.
• Spec versioning — as the API evolves, we'll tag spec releases and document breaking changes in the changelog.

The spec is open. The types are generated. The plugin interfaces are defined. The rest is up to you — we can't wait to see what you build.

@1claw/openapi-spec on npm · @1claw/sdk on npm · SDK docs · ops@1claw.xyz