Records and secrets

A record is one logical secret in a project. A General record has one encrypted value; a record with access_scope: environment may hold separate Development, Staging and Production values under the same record identity. Plaintext is encrypted and decrypted in the SDK, CLI, Web app, or local MCP process. Choose General or By Environment when creating the record. This access_scope cannot change after saving, but authorized users can edit its values and metadata. An Environment record may start incomplete; requesting a missing value returns an error rather than another Environment’s value. General is an access scope, not a fourth Environment. A record with secret_format: env still stores environment-variable content; that format and its target_env field are separate from access_scope. In the Web app, every record shows its access scope separately from its health state. General or Per environment describes how values are scoped. Healthy, Expiring, Critical, or Expired comes from the record’s due date. Neither indicator replaces or implies the other. Human access still follows the existing project/record roles and shares: a person who may read the secret can see its Environment values. A PAT or Service Account token adds a narrower selection of general, development, staging, and production scopes. Select at least one when creating the credential; an authorized owner/admin can edit that selection later. Existing credentials without a saved selection are General-only until edited. These token scopes do not grant project membership or bypass RBAC. For example, one PAT may allow General and Staging. The same PAT reads a General record without environment and a By Environment record with environment: 'staging'; it cannot read that record’s Production value. A Service Account credential may allow Production instead, but it still needs its assigned role, project access and a record or project key wrapper. The AI Agents wizard asks for scopes when it creates a PAT and shows the saved scopes when you select an existing PAT; it does not create a Service Account.

Choose the right surface

Use the SDK inside an application or script.
Use the CLI to inject records into a child process without writing a .env file.
Use MCP when an agent needs an approved action.
Use the raw API for metadata and pre-encrypted payloads. Prefer the SDK for values because it performs the required cryptography.

Read one record

SDK

const secret = await airctrl.getSecret({
  recordId: '00000000-0000-4000-8000-000000000100',
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
})

console.log(secret.name)

getSecret returns the decrypted value and parsed fields. The decryption happens in your process. Pass secret.fields only to the trusted code that needs it; do not log the value. Use readRecord when you want selected sections instead of the complete record:

const record = await airctrl.readRecord({
  recordId: '00000000-0000-4000-8000-000000000100',
  scope: ['meta', 'fields'],
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
})

scope accepts fields, meta, owner, access, or full. Requesting fields decrypts the complete field map; it does not select individual field names. Omit environment for General, or pass development, staging, or production to read exactly that value; an absent value never falls back to another scope. If your application uses an AC_ENVIRONMENT variable, read it in your application and pass it as the SDK’s environment argument. The SDK does not guess from NODE_ENV, the PAT, or the deployment. See SDK examples for a validated TypeScript example. CLI uses --env; MCP uses the environment tool input.

CLI

Print only the secret value:

airctrl get 00000000-0000-4000-8000-000000000100

Read structured fields and metadata:

airctrl read 00000000-0000-4000-8000-000000000100 --scope meta,fields

MCP

The MCP server reads the vault passphrase from AIRCTRL_MCP_VAULT_PASSWORD, never from the prompt.

An agent can see values returned by a record tool. Only call a decryption tool when the model is allowed to receive that secret.

Read the fields section of record "00000000-0000-4000-8000-000000000100"
locally. This gives the local MCP client and agent the complete decrypted field map.
Use it only for this task. Do not print, log or repeat the values in your response.

MCP tool used: read_record

Inject a project into a process

The CLI converts record names to uppercase environment variable names and injects them only into the child process.

airctrl run --project 00000000-0000-4000-8000-000000000010 -- node server.js

For example, Database URL becomes DATABASE_URL. control variables are removed before the child starts. SDK equivalent:

const records = await airctrl.getAll({
  projectId: '00000000-0000-4000-8000-000000000010',
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
})

const environment = Object.fromEntries(
  records.map((record) => [record.name, record.value]),
)

These examples select General. For Staging, pass --env staging to airctrl run or environment: 'staging' to getAll. Neither call mixes General and Staging values:

airctrl run --project 00000000-0000-4000-8000-000000000010 --env staging -- node server.js

const stagingRecords = await airctrl.getAll({
  projectId: '00000000-0000-4000-8000-000000000010',
  environment: 'staging',
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
})

MCP is different

MCP does not inject values into a child process. It returns tool results to the agent. Prefer the CLI when the goal is only to start an application without a .env file. A bulk MCP read exposes decrypted values to the agent, so use it only in an approved context. When the agent is explicitly allowed to use every accessible value in one project, ask:

Load accessible General records from project
"00000000-0000-4000-8000-000000000010" for this task. Do not load any
Development, Staging or Production values. Use the values only as runtime
input. Do not print, summarize or retain them.

For Staging instead:

Load only the Staging values of accessible records from project
"00000000-0000-4000-8000-000000000010" for this task. Do not load General
or Production. Use the values only as runtime input. Do not print, summarize
or retain them.

MCP tool used: get_all

Create a record

Use createSecret with the fields required by the selected secret format:

const result = await airctrl.createSecret({
  projectId: '00000000-0000-4000-8000-000000000010',
  name: 'Payments database',
  secretFormat: 'database',
  fieldValues: {
    engine: 'postgres',
    host: { host: 'db.internal.example', port: 5432 },
    database_name: 'payments',
    username: 'payments-app',
    password: process.env.SOURCE_DATABASE_PASSWORD!,
  },
  tags: ['payments', 'production'],
  idempotencyKey: '00000000-0000-4000-8000-000000000120',
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
})

console.log(result.recordId)

The CLI example uses the simpler plain format; the SDK example above shows the typed database fields. The CLI returns the new record ID:

airctrl create plain \
  --project 00000000-0000-4000-8000-000000000010 \
  --name "Payments CLI token" \
  --field body="$SOURCE_DEV_TOKEN" \
  --env development

Avoid placing sensitive field values directly in shell history. For files of environment variables, use:

airctrl import env ./source.env \
  --project 00000000-0000-4000-8000-000000000010 \
  --name "Payments environment" \
  --target-env production

--target-env is metadata inside the env secret format; it does not select the record’s access scope. Use --env production separately when you want to create or read the Production value of a By Environment record. For an ENV-format record whose value itself is scoped to Production, pass both flags. This is a different record from the General example above:

airctrl import env ./source.env \
  --project 00000000-0000-4000-8000-000000000010 \
  --name "Payments runtime variables" \
  --target-env production --env production

One record with separate Environment values

Create a partially filled record and add another value later through the same SDK writer. Both values belong to one record and share its existing project/record access rules:

const { recordId } = await airctrl.createSecret({
  projectId: '00000000-0000-4000-8000-000000000010',
  name: 'Payments token',
  secretFormat: 'plain',
  accessScope: 'environment',
  environmentValues: [
    { environment: 'development', fieldValues: { body: process.env.SOURCE_DEV_TOKEN! } },
  ],
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
})

await airctrl.setSecret({
  recordId,
  environment: 'staging',
  fieldValues: { body: process.env.SOURCE_STAGE_TOKEN! },
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
})

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

Production remains empty until an authorized user adds its value. A Production read does not return Staging or Development as a substitute. The same flow through the CLI uses the record ID returned by create, not a second record name:

airctrl record set "$RECORD_ID" --field body="$SOURCE_STAGE_TOKEN" --env staging
airctrl get "$RECORD_ID" --env staging

To create an Environment record without manually supplying a value, use the existing generator once for each selected variant:

await airctrl.createGeneratedRecord({
  projectId: '00000000-0000-4000-8000-000000000010',
  name: 'Deployment certificates',
  secretFormat: 'certificate',
  accessScope: 'environment',
  environmentValues: [
    { environment: 'development', options: { cn: 'dev.example.invalid' } },
    { environment: 'staging', options: { cn: 'stage.example.invalid' } },
    { environment: 'production', options: { cn: 'prod.example.invalid' } },
  ],
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
})

Each value is generated independently under one logical record and its existing key/wrappers. You can also generate only one variant and add another later.

MCP

Supply secret values only when the model is authorized to receive them.

Create a database record named "Payments database" in project
"00000000-0000-4000-8000-000000000010" using engine, host, username and
password from the approved local secret source. Show the project, name,
format and field names, but never the field values. Wait for my confirmation
before creating it.

MCP tool used: create_record

Generate one Staging value with MCP

For an Environment record without putting a secret value in the prompt, ask the local MCP server to generate one variant:

Create an SSH record named "Deployment key" in project
"00000000-0000-4000-8000-000000000010" for Staging only. Generate the
key locally with host "stage.example.invalid" and username "deploy". Show
the project, record name, format and Environment, then wait for my
confirmation. Do not print the private key.

MCP tool used: create_record with generate: true, environment: 'staging', and the SSH host/username generator options.

Generate a new secret

can generate supported material locally and store it in one operation. Supported generators include passwords, API keys, TOTP seeds, SSH keys, certificates, webhook secrets, and OAuth client secrets.

await airctrl.createGeneratedRecord({
  projectId,
  name: 'Webhook signing key',
  secretFormat: 'webhook',
  extraFields: {
    webhook_name: 'Payments webhook',
    endpoint_url: 'https://example.invalid/hooks/payments',
  },
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
})

airctrl new certificate --project "$PROJECT_ID" --name "Generated TLS certificate" --cn api.example.invalid

MCP request:

Create a webhook record named "Webhook signing key" in project
"00000000-0000-4000-8000-000000000010". Set webhook_name to "Payments
webhook" and endpoint_url to "https://example.invalid/hooks/payments";
generate the signing secret locally. Show only non-secret details and wait
for my confirmation. Never print the generated value.

MCP tool used: create_record with generate: true

Update, rotate and roll back

setSecret saves a new encrypted value version.
rotateRecord creates a new data key, reciphers current values and stores the prior key encrypted by the client for historical rollback.
rollbackRecordToVersion opens an earlier version locally and appends it encrypted under the current data key, without deleting history.
updateRecordMetadata changes name, tags, due date, or rotation interval without changing the value.

CLI equivalents are set, record rotate, record rollback, and record metadata. MCP equivalents are set_secret, rotate_record, rollback_record, and update_record_metadata. Rollback chooses the variant from the historical version ID. It does not take an Environment flag. For example, to restore an earlier Development value while leaving Staging and Production unchanged:

const versions = await airctrl.getRecordVersions(recordId)
const selectedVersion = versions.find((version) =>
  version.version_id === selectedVersionId && version.environment === 'development',
)
if (!selectedVersion) throw new Error('Select a Development version from history')
await airctrl.rollbackRecordToVersion(recordId, selectedVersion.version_id, process.env.AIRCTRL_VAULT_PASSPHRASE!)

Sharing encrypts the record key for the recipient. It does not share your vault passphrase.The same pattern exists for Service Accounts and groups. CLI uses record share-user, share-sa, share-group and their matching revoke-* commands.

await airctrl.shareRecordWithUser({
  recordId,
  granteeUserId,
  permission: 'read',
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
})

await airctrl.revokeRecordFromUser(recordId, granteeUserId)

MCP request:

Give user "00000000-0000-4000-8000-000000000050" read access to record
"00000000-0000-4000-8000-000000000020". Confirm both resources and wait for
my approval. After I confirm, change only this direct user grant.

To remove that direct grant later:

Remove user "00000000-0000-4000-8000-000000000050" from record
"00000000-0000-4000-8000-000000000020". Explain that access will end
immediately and wait for my confirmation. Do not change any other grant.

MCP tools used: share_record_user, revoke_record_user

History and audit

Use record versions, record audit, anomalies, activity, alerts, and access feeds to understand changes without exposing plaintext. Project-scoped audit feeds require audit:read. Navigable record audit, alert, and access feeds use stable cursor pagination. Start with limit, then pass the returned pagination.next_cursor as cursor without changing scope, action, actor, or date filters. The cursor is opaque. Legacy offset remains available for existing clients but cannot be combined with cursor. GET /records/{id}/audit keeps its original array response; use GET /records/{id}/audit/events or listRecordAudit() for server-side filtering and stable pagination.

Common failures

403 not_authorized: the caller lacks record access or the required action permission.
404 record_not_found: the ID is wrong or unavailable in the active account.
409 record_name_exists: another record already uses that name where uniqueness is required.
409 project_not_keyed: refresh project key state before retrying the operation.

Getting Started

Guides

Reference

Records and secrets

Choose the right surface

Read one record

SDK

CLI

MCP

Inject a project into a process

MCP is different

Create a record

One record with separate Environment values

MCP

Generate one Staging value with MCP

Generate a new secret

Update, rotate and roll back

History and audit

Common failures

​Choose the right surface

​Read one record

​SDK

​CLI

​MCP

​Inject a project into a process

​MCP is different

​Create a record

​One record with separate Environment values

​MCP

​Generate one Staging value with MCP

​Generate a new secret

​Update, rotate and roll back

​Share and revoke

​History and audit

​Common failures

Choose the right surface

Read one record

SDK

CLI

MCP

Inject a project into a process

MCP is different

Create a record

One record with separate Environment values

MCP

Generate one Staging value with MCP

Generate a new secret

Update, rotate and roll back

Share and revoke

History and audit

Common failures