SDK methods - AIRCTRL

All methods below belong to AirctrlClient. Method names are the stable developer bindings verified against the public API. For a runnable TypeScript example of every method, continue to SDK examples.

Identity availability

A human PAT may call every method on this page when RBAC permits it. A Service Account may call only:

listRecords() and listProjectRecords().
getSecret(), readRecord() and getAll().
listProviders().
getGateway(), listGatewayTokens(), listGatewayLogs(), getGatewayLogDetail() and listGatewayKeyAccess().

Every other method is human-only. The SDK does not turn a human-only API operation into a Service Account operation. RBAC and record key access can further reduce what either identity may do.

Context and projects

Method	Purpose
`listAccounts()`	List accounts the authenticated human can access.
`listProjects({ accountId, includeArchived? })`	List accessible projects in one account.
`getProject(projectId, { accountId })`	Read one project or return `null`.
`createProject(input)`	Create a project and make the creator Project Administrator.
`updateProject(projectId, input, { accountId })`	Replace project name, description and active state.
`setProjectArchiveState(projectId, archived, { accountId })`	Archive or restore a project.

Record reading and creation

Method	Purpose
`listRecords(input?)`	List record metadata across accessible account scope.
`listProjectRecords(projectId, input?)`	List metadata for one project.
`getSecret({ recordId, environment?, vaultPassword? })`	Decrypt one General value or the explicitly selected Environment value locally.
`readRecord({ recordId, scope?, environment?, vaultPassword? })`	Read selected record sections and decrypt the complete fields section when requested.
`getAll({ projectId?, environment?, vaultPassword?, audit? }?)`	Decrypt accessible General values by default, or only values in the selected Environment. Missing variants are omitted; permission and crypto errors still fail.
`createSecret(input)`	Encrypt and create a record from supplied fields. Human mode only.
`createGeneratedRecord(input)`	Generate supported material locally, encrypt it and create a record. Human mode only.
`setSecret(input)`	Update by record ID or upsert by project, name and format. Human mode only.

Method	Purpose
`updateRecordMetadata(recordId, patch)`	Change name, tags, due date or rotation interval.
`setRecordArchiveState(recordId, archived)`	Archive or restore a record.
`transferRecordOwnership(recordId, userId)`	Transfer ownership to another eligible user.
`getRecordVersions(recordId)`	List encrypted version history.
`rollbackRecordToVersion(recordId, versionId, vaultPassword?)`	Open a historical version locally and save it as a new version encrypted under the current data key. Human mode only.
`rotateRecord({ recordId, vaultPassword })`	Rotate the record data key, recipher current values and archive the prior data key encrypted locally.
`shareRecordWithUser(input)`	Encrypt the record key for one user and grant access.
`shareRecordWithServiceAccount(input)`	Encrypt the record key for one Service Account and grant access.
`shareRecordWithGroup(input)`	Encrypt the record key for current group members and grant access.
`revokeRecordFromUser(recordId, userId)`	Remove the direct user grant while preserving independent access paths.
`revokeRecordFromServiceAccount(recordId, serviceAccountId)`	Remove one Service Account grant and wrapper.
`revokeRecordFromGroup(recordId, groupId)`	Remove the group grant; delete wrappers only where effective access is lost.

Record history and audit

Method	Purpose
`getRecordAudit(recordId, limit?)`	Read recent audit events for one record.
`listRecordAudit(recordId, input?)`	Read stable cursor pages with action, actor, and date filters.
`listRecordAnomalies(scope)`	List unusual record events.
`listRecordActivity(day, scope)`	Read daily record activity.
`listRecordAlerts(input)`	Read the paginated record alert feed.
`listRecordAccess(input)`	Read the paginated record access feed.

Providers and gateways

Method	Purpose
`listProviders()`	List enabled AI providers.
`listProviderCredentials(accountId)`	List safe provider credential metadata.
`createProviderCredential(input)`	Validate, encrypt and store a provider credential.
`listProviderCredentialModels(id, { accountId })`	Read the credential’s live catalog, capability tags, supported capabilities and `airctrlSupport` status.
`rotateProviderCredential(id, apiKey, { accountId })`	Replace a provider credential value.
`updateProviderCredentialLabel(id, label, { accountId })`	Rename a provider credential.
`revokeProviderCredential(id, { accountId })`	Revoke a provider credential.
`listGateways(projectId)`	List gateways in one project.
`getGateway(gatewayId)`	Read one gateway and its settings.
`createGateway(input)`	Create a gateway and optionally attach credentials.
`updateGateway(gatewayId, patch, { accountId })`	Update editable gateway details.
`deleteGateway(gatewayId, { accountId })`	Disable a gateway and revoke its tokens.
`updateGatewaySettings(gatewayId, patch, { accountId })`	Update limits, logging, guardrails or models.
`attachGatewayCredential(gatewayId, credentialId, modelIds, { accountId })`	Validate several models with one live catalog and attach every exact key/model binding.
`detachGatewayCredential(gatewayId, credentialId, { accountId })`	Detach a provider credential without revoking it.
`detachGatewayCredentialModel(gatewayId, credentialId, modelId, { accountId })`	Remove one exact model binding while keeping the credential and its other models attached.

Gateway tokens

Method	Purpose
`listGatewayTokens(gatewayId)`	List safe token metadata.
`createGatewayToken(gatewayId, input, { accountId })`	Create a gateway token and return its value once.
`renameGatewayToken(gatewayId, tokenId, name, { accountId })`	Change the token display name.
`revokeGatewayToken(gatewayId, tokenId, { accountId })`	Stop the token from authenticating.
`deleteGatewayToken(gatewayId, tokenId, { accountId })`	Delete token metadata.

Gateway observability

Method	Purpose
`listGatewayLogs(gatewayId, input?)`	Filter one gateway’s request metadata and, when authorized, full-text search stored bodies.
`getGatewayLogDetail(gatewayId, logId)`	Read stored request and response bodies.
`listGatewayKeyAccess(gatewayId, input?)`	List provider credential access outcomes.
`listUsageLogs(input)`	List usage and correlation across project gateways.
`getUsageLogDetail(projectId, logId)`	Read one project usage log body.
`getUsageSpend(projectId, gatewayId?)`	Compare spend with effective project or gateway limits.
`getUsageMetrics(projectId, input?)`	Read filterable project or gateway request, error, token, latency and spend metrics.
`getGatewayOtelExport(gatewayId, { accountId })`	Read safe OpenTelemetry export settings.
`updateGatewayOtelExport(gatewayId, patch, { accountId })`	Update OpenTelemetry metrics, traces, optional bodies, endpoint or headers. Request events are automatic while export is enabled.

listGatewayLogs and listUsageLogs return pagination.next_cursor. Continue by passing it as cursor with the same scope and filters. Cursor and legacy offset are mutually exclusive.

Service Account metadata

Method	Purpose
`listServiceAccounts({ accountId })`	List safe Service Account metadata.
`getServiceAccount(serviceAccountId, { accountId })`	Find one Service Account or return `null`.

These metadata methods require a human PAT. The table above is the supported developer binding layer. The package separately exports advanced first-party primitives used by the Web app and CLI for Service Account credential lifecycle and identity rotation. Their presence does not create equivalent lifecycle commands or tools in the public CLI or MCP server; consult the installed TypeScript declarations before deliberately integrating those lower-level exports.

Groups and access material

These methods require a human PAT. Team+ enables collaboration; RBAC and PAT scope still apply. Revocation does not need a vault unlock. See effective access and pending material.

Method	Purpose
`listGroups(projectId, { accountId })`	List groups associated with the project context and their grants.
`getGroupCatalog(projectId, { accountId })`	List available account groups, delegable roles and caller permissions.
`getRecordGroupCatalog(recordId, { accountId })`	List group sharing options with `granted`, `canShare` and `canRevoke`.
`createGroup(projectId, input, { accountId })`	Create a reusable account group; does not grant a project role.
`updateGroup(groupId, input, { accountId })`	Replace name and description; omitted description clears it.
`deleteGroup(groupId, { accountId })`	Remove the group and reconcile affected access paths.
`listGroupMembers(groupId, { accountId, candidates? })`	List members; `candidates: true` also returns eligible account users and membership flags.
`addGroupMember(groupId, userId, { accountId })`	Persist membership across the group’s existing grants.
`removeGroupMember(groupId, userId, { accountId })`	Remove this membership without revoking other access paths.
`grantProjectGroup(projectId, groupId, roleId, { accountId })`	Assign a delegable project role to the group.
`revokeProjectGroup(projectId, groupId, roleId, { accountId })`	Remove only that project/group/role grant.
`reconcileGroupAccess(input)`	Attempt pending encrypted-material repair with an authorized holder’s unlocked vault.

Membership, deletion and project-grant results include changed, wrappersDeleted, projectWrappersDeleted and per-resource changes. These are server snapshots, not proof of completed client encryption. Inspect material_pending, rekey_queued and remaining sources. Reconciliation returns attemptedProjectIds; missing holder material can remain pending. Optional projectIds restrict projects, not pending direct group-record repairs in the account. Reconciliation does not grant permissions.

Exact method signatures

Optional values end with ?. Input types are exported by @airctrl/sdk, so your editor can show every field and accepted value. For readRecord, scope accepts record sections only: fields, meta, owner, access, or full. fields decrypts and returns the complete field map; it does not select individual field names. Omit environment for General, or pass development, staging, or production to select that value. A missing value never falls back to another scope; the PAT or Service Account token must permit the selection.

Context and projects

listAccounts()
listProjects(input: ListProjectsInput)
getProject(projectId: string, options: { accountId: string })
createProject(input: CreateProjectInput)
updateProject(projectId: string, input: UpdateProjectInput, options: { accountId: string })
setProjectArchiveState(projectId: string, archived: boolean, options: { accountId: string })

Groups

listGroups(projectId: string, options: { accountId: string })
getGroupCatalog(projectId: string, options: { accountId: string })
getRecordGroupCatalog(recordId: string, options: { accountId: string })
createGroup(projectId: string, input: GroupInput, options: { accountId: string })
updateGroup(groupId: string, input: GroupInput, options: { accountId: string })
deleteGroup(groupId: string, options: { accountId: string })
listGroupMembers(groupId: string, options: { accountId: string; candidates?: boolean })
addGroupMember(groupId: string, userId: string, options: { accountId: string })
removeGroupMember(groupId: string, userId: string, options: { accountId: string })
grantProjectGroup(projectId: string, groupId: string, roleId: string, options: { accountId: string })
revokeProjectGroup(projectId: string, groupId: string, roleId: string, options: { accountId: string })
reconcileGroupAccess(input: { accountId: string; projectIds?: string[]; vaultPassword: string })

GroupInput has required name: string and optional description: string. Keep the passphrase local; vaultPassword is the existing SDK parameter name.

Records

listRecords(input: ListRecordsInput = {})
listProjectRecords(projectId: string, input: ListProjectRecordsInput = {})
getSecret(params: { recordId: string; vaultPassword?: string; audit?: boolean; environment?: RecordEnvironment })
readRecord(params: { recordId: string; vaultPassword?: string; scope?: string[]; environment?: string; audit?: boolean })
getAll(params?: { projectId?: string; vaultPassword?: string; audit?: boolean; environment?: RecordEnvironment })
createSecret(params: CreateSecretInput & { vaultPassword?: string })
createGeneratedRecord(params: CreateGeneratedRecordInput & { vaultPassword?: string })
setSecret(input: SetSecretInput)
updateRecordMetadata(recordId: string, patch: UpdateRecordMetadataInput)
setRecordArchiveState(recordId: string, archived: boolean)
transferRecordOwnership(recordId: string, newOwnerUserId: string)
getRecordVersions(recordId: string)
getRecordAudit(recordId: string, limit = 100)
rollbackRecordToVersion(recordId: string, targetVersionId: string, vaultPassword?: string)
rotateRecord(params: { recordId: string; vaultPassword?: string })
shareRecordWithUser(params: { recordId: string; granteeUserId: string; permission?: 'view' | 'read'; vaultPassword?: string })
shareRecordWithServiceAccount(params: { accountId: string; recordId: string; serviceAccountId: string; vaultPassword?: string })
shareRecordWithGroup(params: { recordId: string; groupId: string; vaultPassword?: string })
revokeRecordFromUser(recordId: string, granteeUserId: string)
revokeRecordFromServiceAccount(recordId: string, serviceAccountId: string)
revokeRecordFromGroup(recordId: string, groupId: string)
listRecordAnomalies(input: RecordAuditScope = {})
listRecordActivity(day: string, input: RecordAuditScope = {})
listRecordAudit(recordId: string, input: ListRecordAuditInput = {})
listRecordAlerts(input: RecordAuditScope & { limit?: number; cursor?: string; offset?: number } = {})
listRecordAccess(input: RecordAuditScope & { limit?: number; cursor?: string; offset?: number; actions?: string[] } = {})

Providers and gateways

listProviders()
listProviderCredentials(accountId: string)
createProviderCredential(input: CreateProviderCredentialInput)
listProviderCredentialModels(credentialId: string, options: { accountId: string })
rotateProviderCredential(credentialId: string, apiKey: string, options: { accountId: string })
updateProviderCredentialLabel(credentialId: string, label: string, options: { accountId: string })
revokeProviderCredential(credentialId: string, options: { accountId: string })
listGateways(projectId: string)
getGateway(gatewayId: string)
createGateway(input: CreateGatewayInput)
updateGateway(gatewayId: string, patch: UpdateGatewayInput, options?: { accountId?: string })
deleteGateway(gatewayId: string, options?: { accountId?: string })
attachGatewayCredential(gatewayId: string, credentialId: string, modelIds: string[], options?: { accountId?: string })
detachGatewayCredential(gatewayId: string, credentialId: string, options?: { accountId?: string })
detachGatewayCredentialModel(gatewayId: string, credentialId: string, modelId: string, options?: { accountId?: string })
updateGatewaySettings(gatewayId: string, patch: UpdateGatewaySettingsInput, options?: { accountId?: string })
listGatewayTokens(gatewayId: string)
createGatewayToken(gatewayId: string, input: CreateGatewayTokenInput, options?: { accountId?: string })
renameGatewayToken(gatewayId: string, tokenId: string, name: string, options?: { accountId?: string })
revokeGatewayToken(gatewayId: string, tokenId: string, options?: { accountId?: string })
deleteGatewayToken(gatewayId: string, tokenId: string, options?: { accountId?: string })
listGatewayLogs(gatewayId: string, input: ListGatewayLogsInput = {})
getGatewayLogDetail(gatewayId: string, logId: string)
listGatewayKeyAccess(gatewayId: string, input: ListGatewayKeyAccessInput = {})
listUsageLogs(input: ListUsageLogsInput)
getUsageLogDetail(projectId: string, logId: string)
getUsageSpend(projectId: string, gatewayId?: string)
getUsageMetrics(projectId: string, input: {
  since?: string
  until?: string
  bucket?: UsageBucket
  gatewayId?: string
  provider?: string
  model?: string
  statusClass?: '2xx' | '4xx' | '5xx' | 'other'
  search?: string
} = {})
getGatewayOtelExport(gatewayId: string, options?: { accountId?: string })
updateGatewayOtelExport(gatewayId: string, patch: UpdateOtelExportInput, options?: { accountId?: string })

Service Account metadata

listServiceAccounts(options: { accountId: string })
getServiceAccount(serviceAccountId: string, options: { accountId: string })

Input and result rules

IDs are UUID strings. Keep account, project, record, gateway, token and credential IDs separate.
Methods with accountId select the active account. The value never grants access.
List methods return arrays or paginated objects. Empty access returns an empty result, not broader data.
getProject() and getServiceAccount() can return null when the resource is unavailable.
Write methods that create a resource return its new identifier or resource metadata.
Methods that return no resource resolve successfully without a value.
Record plaintext is accepted or returned only by client-side crypto methods. Raw HTTP methods work with encrypted material.
Provider secrets and newly created gateway tokens are one-time values. Do not log their result.

End-to-end examples

Create a project, then create an encrypted record inside it:

const project = await airctrl.createProject({
  accountId,
  name: "Payments",
  description: "Credentials for the payments service",
});

const record = await airctrl.createSecret({
  projectId: project.project_id,
  name: "Database URL",
  secretFormat: "plain",
  fieldValues: { body: process.env.SOURCE_DATABASE_URL! },
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
});

Read only metadata first, then decrypt only when the process needs the value:

const records = await airctrl.listProjectRecords(projectId);
const selected = records.find((record) => record.name === "Database URL");

if (!selected) throw new Error("Record not found");

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

Create a gateway token and display the one-time value only to the custody step:

const token = await airctrl.createGatewayToken(
  gatewayId,
  {
    name: "Payments development",
    scopes: ["run", "read_logs"],
    expiresInDays: 30,
    allowedModels: ["gpt-5.4-mini"],
  },
  { accountId },
);

await custody.write(token.plaintext);

Read project-wide usage without requesting stored request bodies:

const [metrics, spend] = await Promise.all([
  airctrl.getUsageMetrics(projectId, { gatewayId, bucket: "day" }),
  airctrl.getUsageSpend(projectId),
]);

Failure behavior

Every API failure throws AirctrlError. Inspect its fields instead of parsing prose.

Field	Meaning
`status`	HTTP status returned by .
`code`	Stable error category when the API provides one.
`message`	Specific reason for the failure.
`details`	Optional validation or conflict details.

try {
  await airctrl.updateRecordMetadata(recordId, { name: "" });
} catch (error) {
  if (!(error instanceof AirctrlError)) throw error;

  if (error.status === 400) {
    console.error("Fix the submitted metadata", error.details);
  } else if (error.status === 403) {
    console.error(
      "The current identity cannot perform this action",
      error.code,
    );
  } else {
    throw error;
  }
}

Do not retry 400, 403, or 404 unchanged. Retry temporary 429, 500, or 503 failures with bounded exponential backoff. Reuse the same idempotency key only for the same intended write.

OAuth partner backend

OAuth partner methods run only in a confidential backend. Keep the client secret and every returned token in a secret manager; never send them to browser storage or logs. Use createPkce() for each authorization transaction. It returns a fresh 43-character verifier and its SHA-256 base64url challenge; persist the verifier only in the short-lived server transaction. Every OAuth App remains owned and managed by the organization that registered it. A private App can be installed only there. A public App presents an organization selector containing only active organizations where the approving user holds oauth-installations:connect; each resulting installation and token remains bound to the selected customer organization. Active subscription, trial, and payment-retry (past_due) states qualify. The SDK flow and its protection, logs, and spend methods are otherwise identical for private and public Apps; the installation binding enforces the organization boundary. Use Discover the authorization server to select Production or QA and read the current authorization, token, and revocation endpoints. Local development values are in Environments. implements OAuth 2.0 authorization, not OpenID Connect login: it intentionally does not issue ID Tokens or expose a UserInfo endpoint.

const authorize = oauth.authorizationUrl(request);
const tokens = await oauth.exchangeCode(callback);
const providers = await oauth.listProvisioningProviders(tokens.access_token);
const provider = providers.find((candidate) => candidate.slug === selectedProviderSlug);
if (!provider) throw new Error("provider_unavailable");
const preview = await oauth.preflightProtection(tokens.access_token, {
  providerId: provider.provider_id,
  otel: false,
});
if (!preview.allowed) throw new Error(preview.blockers.join(", "));
const catalog = await oauth.discoverProvisioningProviderModels(
  tokens.access_token,
  provider.provider_id,
  providerKey,
);
if (catalog.invalidApiKey) throw new Error("provider_key_invalid");
for (const model of catalog.models) {
  // Numeric token prices are USD per 1M tokens. These fields preserve
  // provider-published zero prices and context-tiered rate cards.
  console.log(model.id, model.pricing?.displayText, model.pricing?.rateCard);
}
const protection = await oauth.provisionProtection(
  tokens.access_token,
  idempotencyKey,
  {
    externalResourceId: externalKeyId,
    providerId: provider.provider_id,
    providerKey,
    gatewayName: "Support AI",
    models: ["model-standard"],
  },
);
const protections = await oauth.listProtections(tokens.access_token);
const currentProtection = await oauth.getProtection(
  tokens.access_token,
  protection.protectionId,
);
const logs = await oauth.listProtectionLogs(
  tokens.access_token,
  protection.protectionId,
  { limit: 50 },
);
const spend = await oauth.getProtectionSpend(
  tokens.access_token,
  protection.protectionId,
);
await oauth.updateProtection(tokens.access_token, protection.protectionId, {
  gatewayName: currentProtection.gateway.name,
  settings: { rateLimitPerMin: 240 },
});
const nextTokens = await refreshLock.run(installationId, async () => {
  const current = await encryptedTokenStore.require(installationId);
  const next = await oauth.refresh(current.refresh_token!);
  await encryptedTokenStore.compareAndSwap(current.refresh_token!, next);
  return next;
});
await oauth.revoke(nextTokens.refresh_token ?? nextTokens.access_token);

Every protected external key returns its own protectionId. Store that ID next to the partner’s stable external key ID. Lifecycle calls never accept the parent OAuth connection ID.

await oauth.rotateProtectionProviderKey(
  tokens.access_token,
  protection.protectionId,
  replacementProviderKey,
);
const rotated = await oauth.rotateProtectionRuntimeToken(
  tokens.access_token,
  protection.protectionId,
  runtimeRotationIdempotencyKey,
);
await oauth.revokeProtection(tokens.access_token, protection.protectionId);
const reactivated = await oauth.reactivateProtection(
  tokens.access_token,
  protection.protectionId,
  reactivationIdempotencyKey,
);

The preflight performs no writes and receives no provider key. On the first successful protection, creates one internal Service Account and one dedicated project for the connection. Each protection then creates one encrypted provider credential, one independently configured gateway, its model bindings and one runtime gateway token. The provider key is validated and encrypted at rest; it is never returned. The same idempotency key may only replay the same request. Serialize refreshes per installation; concurrent reuse revokes the refresh-token family. If a newer runtime-token operation supersedes an older idempotency key, returns idempotency_operation_superseded. Omit otel.headers in updateProtection() to preserve current headers; send null or {} to clear them. Disconnecting revokes OAuth/runtime access and disables the internal Service Account. It never deletes the project, credentials, gateways, settings, logs or audit history. OAuthPartnerClient failures throw AirctrlOAuthError, not AirctrlError. Inspect status, error, and optional description; do not parse the message string.

SDK helper: createPkce()SDK types: OAuthScope, OAuthTokenSet, OAuthGatewaySettings, OAuthProtection, OAuthGatewayPreflight, OAuthProvider, OAuthProviderModel, OAuthProviderModelCapability, OAuthProviderModelPricing, OAuthProviderModelsDiscovery, OAuthProtectionProvisionInput, OAuthProtectionUpdateInput, OAuthProtectionLog, OAuthProtectionLogs, and OAuthProtectionSpendSDK method: authorizationUrl()SDK method: exchangeCode()SDK method: refresh()SDK method: revoke()SDK method: listProvisioningProviders()SDK method: discoverProvisioningProviderModels()SDK method: preflightProtection()SDK method: provisionProtection()SDK method: listProtections()SDK method: getProtection()SDK method: updateProtection()SDK method: listProtectionLogs()SDK method: getProtectionSpend()SDK method: revokeProtection()SDK method: rotateProtectionProviderKey()SDK method: rotateProtectionRuntimeToken()SDK method: reactivateProtection()

​Identity availability

​Context and projects

​Record reading and creation

​Record lifecycle and sharing

​Record history and audit

​Providers and gateways

​Gateway tokens

​Gateway observability

​Service Account metadata

​Groups and access material

​Exact method signatures

​Input and result rules

​End-to-end examples

​Failure behavior

​OAuth partner backend

Identity availability

Context and projects

Record reading and creation

Record lifecycle and sharing

Record history and audit

Providers and gateways

Gateway tokens

Gateway observability

Service Account metadata

Groups and access material

Exact method signatures

Input and result rules

End-to-end examples

Failure behavior

OAuth partner backend