> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airctrl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK overview

> Use the typed AIRCTRL client from TypeScript or JavaScript.

export function AirctrlWordmark() {
  return <span className="airctrl-wordmark" aria-label="AIRCTRL">
      <span aria-hidden="true" className="airctrl-wordmark-air">AIR</span>
      <span aria-hidden="true" className="airctrl-wordmark-ctrl">CTRL</span>
    </span>;
}

`@airctrl/sdk` combines the <AirctrlWordmark /> 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 <AirctrlWordmark /> tools](/guides/tool-workflows) when the CLI prepares a developer environment and the SDK performs runtime work.

## Install

```bash theme={}
npm install @airctrl/sdk
```

The package uses ES modules and includes TypeScript declarations.

## Create a human client

```ts theme={}
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.

```ts theme={}
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.

```ts theme={}
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](/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:

```ts theme={}
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 <AirctrlWordmark /> error category when available.
* `message`: safe reason for the failure.
* `details`: optional validation details.

See [Errors and retries](/reference/errors).

## 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](/sdk/methods) for the complete public capability list.