SDK example catalog

import { AirctrlError, createClient } from '@airctrl/sdk'

function required(name: string): string {
  const value = process.env[name]
  if (!value) throw new Error(`Missing ${name}`)
  return value
}

const airctrl = createClient({
  baseUrl: required('AIRCTRL_API_URL'),
  auth: required('AIRCTRL_TOKEN'),
})

const accountId = required('AIRCTRL_ACCOUNT_ID')
const projectId = required('AIRCTRL_PROJECT_ID')
const recordId = required('AIRCTRL_RECORD_ID')
const gatewayId = required('AIRCTRL_GATEWAY_ID')
const vaultPassword = required('AIRCTRL_VAULT_PASSPHRASE')

const accounts = await airctrl.listAccounts()

const projects = await airctrl.listProjects({ accountId, includeArchived: false })

const project = await airctrl.getProject(projectId, { accountId })
if (!project) throw new Error('Project not found')

const project = await airctrl.createProject({ accountId, name: 'Payments', description: 'Payment service credentials' })

await airctrl.updateProject(projectId, { name: 'Payments production', description: 'Production credentials', isActive: true }, { accountId })

await airctrl.setProjectArchiveState(projectId, true, { accountId })
await airctrl.setProjectArchiveState(projectId, false, { accountId })

const page = await airctrl.listRecords({ accountId, includeArchived: false, limit: 50, offset: 0 })

const records = await airctrl.listProjectRecords(projectId, { includeArchived: false, limit: 50, offset: 0 })

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

const selected = await airctrl.readRecord({ recordId, scope: ['username', 'password'], environment: 'production', vaultPassword })

const secrets = await airctrl.getAll({ projectId, vaultPassword, audit: true })

const created = await airctrl.createSecret({ projectId, name: 'Database login', secretFormat: 'password', fieldValues: { username: 'app_user', password: sourcePassword }, tags: ['production'], vaultPassword })

const created = await airctrl.createGeneratedRecord({ projectId, name: 'Generated database password', secretFormat: 'password', options: { length: 32 }, extraFields: { username: 'app_user' }, vaultPassword })

const result = await airctrl.setSecret({ recordId, fieldValues: { username: 'app_user', password: replacementPassword }, changedFields: ['password'], vaultPassword })

await airctrl.updateRecordMetadata(recordId, { tags: ['payments', 'production'], secretDueAt: '2026-12-01T00:00:00Z', rotationIntervalDays: 90 })

await airctrl.setRecordArchiveState(recordId, true)

await airctrl.transferRecordOwnership(recordId, newOwnerUserId)

const versions = await airctrl.getRecordVersions(recordId)

const events = await airctrl.getRecordAudit(recordId, 25)

await airctrl.rollbackRecordToVersion(recordId, targetVersionId)

await airctrl.rotateRecord({ recordId, vaultPassword })

await airctrl.shareRecordWithUser({ recordId, granteeUserId: userId, permission: 'read', vaultPassword })

await airctrl.shareRecordWithServiceAccount({ accountId, recordId, serviceAccountId, vaultPassword })

await airctrl.shareRecordWithGroup({ recordId, groupId, vaultPassword })

await airctrl.revokeRecordFromUser(recordId, userId)

await airctrl.revokeRecordFromServiceAccount(recordId, serviceAccountId)

await airctrl.revokeRecordFromGroup(recordId, groupId)

const anomalies = await airctrl.listRecordAnomalies({ accountId, scopeType: 'project', scopeId: projectId })

const activity = await airctrl.listRecordActivity('2026-09-10', { accountId, scopeType: 'project', scopeId: projectId })

const alerts = await airctrl.listRecordAlerts({ accountId, scopeType: 'project', scopeId: projectId, limit: 25, offset: 0 })

const access = await airctrl.listRecordAccess({ accountId, scopeType: 'project', scopeId: projectId, actions: ['record.secret_access'], limit: 25, offset: 0 })

const providers = await airctrl.listProviders()

const credentials = await airctrl.listProviderCredentials(accountId)

const credential = await airctrl.createProviderCredential({ accountId, providerId, label: 'Production OpenAI', apiKey: process.env.OPENAI_PRODUCTION_KEY!, credentialKind: 'api_key' })

const models = await airctrl.listProviderCredentialModels(credentialId, { accountId })

await airctrl.rotateProviderCredential(credentialId, process.env.OPENAI_REPLACEMENT_KEY!, { accountId })

await airctrl.updateProviderCredentialLabel(credentialId, 'Primary OpenAI', { accountId })

await airctrl.revokeProviderCredential(credentialId, { accountId })

const gateways = await airctrl.listGateways(projectId)

const gateway = await airctrl.getGateway(gatewayId)

const gateway = await airctrl.createGateway({
  accountId,
  projectId,
  name: 'Payments AI',
  defaultProviderId: providerId,
  defaultModel: 'gpt-5',
  credentialBindings: [{ credentialId, modelId: 'gpt-5' }],
})

await airctrl.updateGateway(gatewayId, { name: 'Payments AI production', defaultModel: 'gpt-5', isActive: true }, { accountId })

await airctrl.deleteGateway(gatewayId, { accountId })

await airctrl.attachGatewayCredential(gatewayId, credentialId, 'gpt-5', { accountId })

await airctrl.detachGatewayCredential(gatewayId, credentialId, { accountId })

await airctrl.updateGatewaySettings(gatewayId, { spendLimit: 100, spendWindow: 'monthly', rateLimitPerMin: 120, loggingEnabled: true, logBodies: false, guardrailMode: 'flag', cacheEnabled: true, cacheTtlSeconds: 300 }, { accountId })

const tokens = await airctrl.listGatewayTokens(gatewayId)

const token = await airctrl.createGatewayToken(gatewayId, { name: 'Local development', scopes: ['run', 'read_logs'], expiresInDays: 30, allowedModels: ['gpt-5'], rateLimitPerMin: 60 }, { accountId })
await approvedCustody.write(token.plaintext)

await airctrl.renameGatewayToken(gatewayId, tokenId, 'CI production', { accountId })

await airctrl.revokeGatewayToken(gatewayId, tokenId, { accountId })

await airctrl.deleteGatewayToken(gatewayId, tokenId, { accountId })

const logs = await airctrl.listGatewayLogs(gatewayId, { since: '2026-09-01T00:00:00Z', status: 500, limit: 50, offset: 0 })

const detail = await airctrl.getGatewayLogDetail(gatewayId, logId)

const access = await airctrl.listGatewayKeyAccess(gatewayId, { outcome: 'denied', since: '2026-09-01T00:00:00Z', limit: 50, offset: 0 })

const logs = await airctrl.listUsageLogs({ projectId, gatewayId, since: '2026-09-01T00:00:00Z', limit: 50, offset: 0 })

const detail = await airctrl.getUsageLogDetail(projectId, logId)

const spend = await airctrl.getUsageSpend(projectId)

const metrics = await airctrl.getUsageMetrics(projectId, { since: '2026-09-01T00:00:00Z', bucket: 'day' })

const otel = await airctrl.getGatewayOtelExport(gatewayId, { accountId })

const otelHeaders = JSON.parse(process.env.OTEL_EXPORT_HEADERS_JSON!) as Record<string, string>
await airctrl.updateGatewayOtelExport(gatewayId, { enabled: true, endpoint: 'https://otel.example.com/v1/traces', exportMetrics: true, exportTraces: true, headers: otelHeaders }, { accountId })

const serviceAccounts = await airctrl.listServiceAccounts({ accountId })

const serviceAccount = await airctrl.getServiceAccount(serviceAccountId, { accountId })
if (!serviceAccount) throw new Error('Service Account not found')