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 uses ES modules and includes TypeScript declarations.

Create a human client

import { createClient } from '@airctrl/sdk'

const airctrl = createClient({
  baseUrl: process.env.AIRCTRL_API_URL!,
  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_URL!,
  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. 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.

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.

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

​Read encrypted records

​Account and project context

​Errors

​Idempotency

​Security notes