Service Accounts

A Service Account represents CI, a server, an agent, or another unattended workload. It receives only the custom roles and project access assigned to it.

Security boundary

Creating, pausing, reactivating or deleting a Service Account is Web-only. Provisioning, rotating, revoking and repairing its credential is also Web-only. A human PAT can read safe Service Account metadata through API, SDK, CLI and MCP. A Service Account cannot inspect the account’s Service Account list, including other machine identities. Record sharing is performed by an authorized human through the normal Records capability. Developer tools do not administer the Service Account lifecycle.

Prepare access in the dashboard

Open Settings > Service accounts.
Create the Service Account.
Assign a custom role and the project where it will work.
Open Machine access and provision a credential.
Store the complete credential bundle through the offered save flow or your approved custody system.

The protected credential project stores custody material. It does not grant the Service Account access to unrelated projects or other Service Accounts.

List Service Accounts

API

curl --request GET \
  --url "$AIRCTRL_API_URL/v1/service-accounts?accountId=$AIRCTRL_ACCOUNT_ID" \
  --header "Authorization: Bearer $AIRCTRL_TOKEN" \
  --header "x-account-id: $AIRCTRL_ACCOUNT_ID"

The response contains metadata such as ID, name, active state and revocation time. It never returns tokens, private keys or credential bundles.

SDK

const accounts = await airctrl.listServiceAccounts({ accountId })
const selected = await airctrl.getServiceAccount(serviceAccountId, { accountId })

CLI

airctrl sa list --account "$AIRCTRL_ACCOUNT_ID"
airctrl sa get "$SERVICE_ACCOUNT_ID" --account "$AIRCTRL_ACCOUNT_ID"

MCP

These tools require a human PAT and return metadata only.

Show the Service Accounts in account
"00000000-0000-4000-8000-000000000001". Then show the safe details for
Service Account "00000000-0000-4000-8000-000000000040". Return names, IDs,
providers and states only. Do not change roles, projects, state or credentials.

MCP tools used: list_service_accounts, get_service_account

Use a Service Account with the SDK

Load one complete active credential bundle:

import { readFile } from 'node:fs/promises'
import { createClient, type SaCredentialBundleV1 } from '@airctrl/sdk'

const bundle = JSON.parse(
  await readFile(process.env.AIRCTRL_SA_BUNDLE_PATH!, 'utf8'),
) as SaCredentialBundleV1

const airctrl = createClient({
  baseUrl: bundle.baseUrl,
  auth: bundle.bearer,
  credential: {
    credentialId: bundle.credentialId,
    capPrivateKeyB64: bundle.capPrivateKeyB64,
  },
})

const secret = await airctrl.getSecret({ recordId })

No vault passphrase is required. The capability private key opens the Service Account activation material locally and is never sent to .

Use a Service Account with the CLI

Inject the five active bundle fields through your runtime environment, then run a supported machine command:

airctrl get "$RECORD_ID"
airctrl run --project "$PROJECT_ID" -- node server.js

A Service Account must pass --project to run. The CLI never falls back to a human default project for a machine identity. It may also list accessible records, list providers, and read one accessible gateway’s details, tokens, logs and key-access events. Project creation, record creation, sharing and Gateway configuration remain human-only.

Use a Service Account with MCP

Map the active bundle to the MCP server environment:

AIRCTRL_MCP_API_URL                 = bundle.baseUrl
AIRCTRL_MCP_API_TOKEN               = bundle.bearer
AIRCTRL_MCP_SA_CREDENTIAL_ID        = bundle.credentialId
AIRCTRL_MCP_SA_CAP_PRIVATE_KEY_B64  = bundle.capPrivateKeyB64
AIRCTRL_MCP_SA_SERVICE_ACCOUNT_ID   = bundle.serviceAccountId  # optional

MCP passes the bearer and capability material to @airctrl/sdk. Record values are decrypted locally without a human vault passphrase. In Service Account mode, MCP registers only the supported record and Gateway read tools, plus local status, format-discovery and generation helpers that do not change . It does not register record writes, sharing, project changes, Gateway changes or Service Account administration. RBAC and project access can further reduce the available reads. The record owner or an authorized human encrypts the record key for the Service Account identity. Sharing through any developer surface requires a human PAT. Sharing one record does not expose another record or another Service Account.

await airctrl.shareRecordWithServiceAccount({
  accountId,
  recordId,
  serviceAccountId,
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
})

airctrl record share-sa "$RECORD_ID" \
  --account "$AIRCTRL_ACCOUNT_ID" \
  --service-account "$SERVICE_ACCOUNT_ID"

MCP request:

Give Service Account "00000000-0000-4000-8000-000000000040" access to record
"00000000-0000-4000-8000-000000000020" in account
"00000000-0000-4000-8000-000000000001". Show both resources and wait for my
confirmation. Change only this record grant.

MCP tool used: share_record_service_account

Common failures

service_account_disabled: reactivate it in the dashboard before using its credential.
service_account_revoked: the identity can no longer authenticate.
sa_sealed_unlock_requires_capability: supply the matching credential ID and capability private key.
sa_env_bundle_incomplete: the CLI received only part of an active bundle.
403: the Service Account lacks the required custom-role permission or project grant.

​Security boundary

​Prepare access in the dashboard

​List Service Accounts

​API

​SDK

​CLI

​MCP

​Use a Service Account with the SDK

​Use a Service Account with the CLI

​Use a Service Account with MCP

​Share a record with a Service Account

​Common failures