@oked/sdk

Core library - programmatic approval API for AI agents. Sends sensitive actions to the OKed backend, waits for a human decision, and resolves only when the user approves or denies.

Use this package directly from any Node.js agent (OpenAI SDK, LangChain, custom). For drop-in integrations, see @oked/claude-code or @oked/openclaw.

Install

npm install @oked/sdk

Quick start

import { OKedClient } from "@oked/sdk";

const oked = new OKedClient({
  apiKey: process.env.OKED_API_KEY,
});

const result = await oked.approve({
  action: "deploy",
  description: "Deploy release 2026.04.07 to production",
  tier: "high_stakes",
  session_id: "deploy-123",
  cwd: process.cwd(),
});

if (!result.approved) {
  throw new Error(`Blocked by OKed: ${result.decision}`);
}

Configuration

Pass to new OKedClient(config):

Key	Type	Default	Description
`apiKey`	`string`	`OKED_API_KEY` env	Your OKed API key. Required.
`backendUrl`	`string`	`https://api.oked.ai`	Override the OKed backend URL.
`timeout`	`number`	`300000`	Per-approval timeout in ms.
`strictFailClosed`	`boolean`	`false`	When true, backend outages deny every tier. When false, outages deny only `high_stakes` and allow lower tiers.

API

`approve(request)`

Request an approval for a sensitive action. Resolves when the user responds, the request times out, or the backend denies.

Request fields:

Field	Type	Required	Description
`action`	`string`	yes	Short action identifier (e.g. `"deploy"`, `"send_email"`).
`description`	`string`	yes	Human-readable summary shown in the approval UI.
`tier`	`"safe" \| "warning" \| "review" \| "high_stakes"`	yes	Risk tier. Use `classify()` if unsure.
`tool_input`	`unknown`	no	Raw tool arguments, included in the audit log.
`session_id`	`string`	no	Groups related approvals under one session.
`cwd`	`string`	no	Working directory, shown in the UI for context.

Response fields:

Field	Type	Description
`approved`	`boolean`	`true` only when the user approved.
`approval_id`	`string`	Opaque id for logs / audit.
`decision`	`"approved" \| "denied" \| "timeout"`	Exact outcome.

`ping()`

Returns true when the backend is reachable. Use for startup health checks.

Helpers

classify(input) - classifies a shell command or tool call into a risk tier.
describe(input) - generates a human-readable description for the approval UI.

Full type definitions ship with the package (dist/index.d.ts).

Environment

Var	Required	Description
`OKED_API_KEY`	yes, unless passed in code	Your OKed API key.
`OKED_BACKEND_URL`	no	Override the hosted backend URL.
`OKED_STRICT_FAIL_CLOSED`	no	Set to `1` or `true` to deny every sensitive action when the backend is unreachable.

Degraded-mode behavior

Explicit user denials return { approved: false } and should always be treated as final. Invalid API keys throw OKedAuthError and should deny. If the backend is unreachable, OKedBackendUnreachableError lets integrations apply degraded mode: high_stakes denies, while lower tiers may proceed unless strictFailClosed is enabled. Unexpected errors should be treated as deny.

Development

npm install
npm run build

License

MIT