SDK overview - AIRCTRL

@airctrl/sdk combines the HTTP client, record cryptography and secret-format support. Use it in Node.js applications, scripts, CI workers and local tools. The SDK does not read the CLI login file. Pass its identity explicitly through application configuration. See Combine tools when the CLI prepares a developer environment and the SDK performs runtime work.

Install

npm install @airctrl/sdk

The package requires Node.js 22.x, uses ES modules and includes TypeScript declarations.

Create a human client

import { createClient } from '@airctrl/sdk'

const airctrl = createClient({
  baseUrl: process.env.AIRCTRL_API_ORIGIN!,
  auth: process.env.AIRCTRL_TOKEN!,
})

auth can also be a function. Use this when your application refreshes or resolves the token at call time.

const airctrl = createClient({
  baseUrl: process.env.AIRCTRL_API_ORIGIN!,
  auth: async () => tokenProvider.getToken(),
})

Create a Service Account client

For an active Service Account credential, pass the matching bearer, credential ID and capability private key from one bundle.

const airctrl = createClient({
  baseUrl: bundle.baseUrl,
  auth: bundle.bearer,
  credential: {
    credentialId: bundle.credentialId,
    capPrivateKeyB64: bundle.capPrivateKeyB64,
  },
})

createServiceClient remains available as a compatibility alias. New code should use createClient for both humans and Service Accounts.

Create a confidential OAuth partner client

OAuth partner integrations use a separate client because they authenticate a registered confidential App, not a human PAT or Service Account:

import { OAuthPartnerClient } from '@airctrl/sdk'

const oauth = new OAuthPartnerClient(
  process.env.AIRCTRL_CLIENT_ID!,
  process.env.AIRCTRL_CLIENT_SECRET!,
  {
    apiBaseUrl: process.env.AIRCTRL_API_ORIGIN!,
    webBaseUrl: process.env.AIRCTRL_WEB_URL!,
  },
)

Use this client only in a trusted backend. It uses the configured API/Web bases for authorization, token, revocation, and typed protection operations after consent. Direct HTTP integrations should discover the current endpoint URLs from authorization-server metadata. See Environments, OAuth partner integrations, OAuth protocol, and OAuth protection API. A public App keeps one Client ID and secret in the publisher’s organization while each customer chooses one eligible organization during consent. Tokens, resources, logs, spend, quotas, and billing remain isolated in that selected customer organization. Private Apps preserve the same-organization-only behavior. The client shape is shared, but operation access is not. Service Accounts can use the record and Gateway read operations listed in SDK methods; account administration and resource creation remain human-only.

Supported bindings and advanced primitives

The methods in SDK methods are the supported developer bindings over the public API. The package also exports lower-level first-party primitives used by the Web app and CLI for Service Account credential lifecycle, including AirctrlClient, Session, bootstrap contexts and lifecycle coordinators. Those advanced exports do not imply matching lifecycle commands or tools in the public CLI or MCP server. Use the installed package’s TypeScript declarations as the exact reference when you deliberately integrate those primitives.

Gateway connection URLs

buildGatewayConnectionConfig(apiUrl, gatewaySlug) is the shared URL builder used by the Web app and MCP server. It returns the compatibility base plus native OpenAI, Anthropic, Gemini, Mistral, OpenRouter, HiTheo, Groq, Novita AI, Atlas Cloud, and xAI bases, including the OpenAI, Gemini and Mistral realtime WebSocket URLs.

import { buildGatewayConnectionConfig } from '@airctrl/sdk/gateway-connections'

const connection = buildGatewayConnectionConfig(
  process.env.AIRCTRL_API_ORIGIN!,
  'production-ai',
)

console.log(connection.openrouterBaseUrl)
console.log(connection.hitheoBaseUrl)
console.log(connection.mistralRealtimeUrl)

Append the selected model as the model query parameter for OpenAI and Mistral realtime connections. Authenticate every data-plane connection with a Gateway token, never with the stored provider key.

Read encrypted records

A human passes a vault passphrase to operations that decrypt or create record values:

const secret = await airctrl.getSecret({
  recordId,
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
})

An active Service Account omits the passphrase. Its credential capability opens its cryptographic material locally.

Account and project context

With a human PAT, call listAccounts() first when you do not know the account ID. A Service Account is already bound to one account and cannot enumerate accounts. Methods that act in account context require accountId. Project and resource IDs never replace account context.

Errors

API failures throw AirctrlError with:

status: HTTP status.
code: stable error category when available.
message: safe reason for the failure.
details: optional validation details.

The confidential OAuthPartnerClient is separate from AirctrlClient. Its failures throw AirctrlOAuthError with status, the OAuth or error code, and optional description. See Errors and retries.

Idempotency

The SDK adds an idempotency key to writes. Record creation methods also accept your own stable idempotencyKey. Reuse that value only when retrying the same intended action with the same input.

Security notes

Never log the client options, tokens, bundle or decrypted records.
Keep the vault passphrase and Service Account capability in process memory only as long as needed.
Use named SDK methods. They carry the supported public contract and keep CLI and MCP behavior aligned.
Treat log bodies as sensitive data.

See the SDK method reference for the complete public capability list.

​Install

​Create a human client

​Create a Service Account client

​Create a confidential OAuth partner client

​Supported bindings and advanced primitives

​Gateway connection URLs

​Read encrypted records

​Account and project context

​Errors

​Idempotency

​Security notes