Workspace and resources
Account
An account is the top-level workspace for one company, team, or personal use. It contains members, projects, roles, and billing. An account ID chooses the workspace for a request; it never grants access by itself.Account context
The account selected for a control-plane request. The API usually receives it in thex-account-id
header. checks that the caller belongs to that account, so changing the header cannot expand
what a token is allowed to do.
Project
A project is a workspace inside an account. It groups records, gateways, members, and project-level access. Creating a project makes its creator a Project Administrator for that project only; it does not give access to other projects in the account.Project member
A person who has been added to one specific project. Project membership is separate from account membership. A person can belong to an account but have no access to a particular project.Record
A record is one encrypted secret plus its safe metadata. It can hold an API key, password, environment file, certificate, SSH key, TOTP seed, or another supported secret format.Secret value
The private data inside a record, such as a password or an API key. calls this plaintext only after it has been decrypted in your browser, application, CLI, or local MCP process. The API does not return a record value as ordinary server-side JSON.Record metadata
Non-secret information that helps identify and manage a record, such as its name, format, tags, project, creation time, due date, or health state. Metadata can be listed without revealing the secret value.Secret format
The structure expected for a record. For example, anenv record holds environment variables, a
database record holds database connection fields, and an ssh record holds SSH material. The
format tells which fields are expected and how tools should present them.
Secret field
One named part of a structured record. A database record may havehost, username, and password
fields. A field can be secret even when its name is safe to show.
Credentials and identities
Bearer token
A credential sent asAuthorization: Bearer <token>. Anyone who possesses it can act as its owner,
so keep it out of source code, URLs, logs, and chat prompts.
Personal Access Token (PAT)
A human API credential with the visible prefixsk-actrl-pat-. It acts as the person who created
it and remains limited by that person’s roles, project access, and the token’s scope. It is the
credential for the REST API, SDK, CLI, and human MCP mode.
Service Account
A non-human identity for CI, servers, agents, and other unattended workloads. Its roles and project access are assigned in the dashboard. A Service Account is not a person and does not inherit a creator’s access.Service Account token
A machine bearer token with the visible prefixsk-actrl-sa-. It is one part of an active Service
Account credential and is not a PAT.
Credential bundle
The complete set of values needed to use one active Service Account credential. It includes the API URL, bearer token, credential ID, Service Account ID, and local capability material. Keep the bundle together in one approved secret store; incomplete or mixed bundles fail safely.Capability private key
Private material stored locally with a Service Account credential bundle. It helps the local SDK, CLI, or MCP process unlock that credential’s activation material. It is never sent to and must never be logged or copied into a prompt.Gateway token
A credential used by an application to call one gateway. It is separate from a human PAT and a Service Account token. Gateway tokens belong to the data plane, not the control plane.Provider credential
An API credential for an AI provider, such as OpenAI, Anthropic, or Gemini, stored for use by a gateway. returns only safe metadata after it is saved. Provider credentials are encrypted at rest, but they are a different trust boundary from zero-knowledge record values because the gateway must use them to call the provider.Vault passphrase
The value a person uses to unlock their own record cryptographic material locally. It is not a login password, PAT, Service Account token, or gateway token. never needs it to decrypt a record on the server.Protected credential project
The -managedService Account Credentials project that holds encrypted custody material for
Service Account credential bundles. It exists to support credential recovery and rotation. It does
not give a Service Account access to your ordinary projects or other Service Accounts.
Encryption and sharing
Zero-knowledge
For record values, encryption and decryption happen in the client process. stores encrypted data and encrypted keys without receiving record plaintext. This promise applies to the record vault; it does not mean an AI gateway can route a provider request without using its provider credential.Encryption key
Secret cryptographic material that protects a record value. keeps the record value encrypted and gives an authorized recipient an encrypted copy of the key needed to open that specific record.Record key wrapper
The encrypted package that gives one person or Service Account access to one record’s encryption key. It is created when a record is shared. It does not contain the record value itself and does not grant access to other records.Record share
Giving another person, group, or Service Account access to one record. creates separate encrypted key access for the recipient. Sharing a record does not share your vault passphrase.Direct grant
Access assigned directly to a specific person, group, or Service Account instead of through a broad project role. Removing a direct grant removes only that direct access path.Key rotation
Replacing the encryption key and encrypted value for a record while preserving its history. Use it when a value may have been exposed or when your security policy requires periodic rotation.Access control and requests
RBAC
Role-based access control. checks permissions for every protected action. Permissions from multiple assigned roles add together; a role never overrides a stronger restriction elsewhere.Role
A named set of permissions. Account roles control account-wide actions. Project roles control actions inside a project. A person or Service Account can have more than one role.Permission
One precise capability, such as reading audit data or creating a gateway. Permissions are evaluated with the caller’s account and project access before allows an action.Scope
The boundary where a permission or token applies. In , a scope can mean an account, project, record, gateway, or a token restriction. Always read the nearby documentation because the exact scope depends on the resource being discussed.Least privilege
Giving a person or machine only the roles, project grants, and token access it needs to complete its work. This reduces the damage if a credential is exposed.Principal
The identity making a request. A principal can be a human using a PAT, a Service Account using an active credential, or an application using a gateway token. uses the principal to evaluate access.Web-only
A dashboard action that is intentionally unavailable through the public API, SDK, CLI, and MCP. Examples include managing account members and the Service Account credential lifecycle. This keeps high-impact administration supervised in the UI.Idempotency key
A unique value sent with a write request so a network retry does not create the same resource twice. Reuse the same key only when retrying the same request. Using it with different request data returns an error instead of guessing which request you intended.Resource ID
The stable identifier for an account, project, record, gateway, or other resource. Examples in the documentation use fictional IDs. Ask to list or create a resource instead of inventing an ID in a real request.Gateways and AI traffic
Control plane
The API used to configure projects, records, gateways, tokens, provider credentials, and related settings. It uses a human PAT or Service Account credential and normally has paths beginning with/v1/.
Data plane
The gateway endpoints that receive an application’s AI requests and forward them according to gateway configuration. Your AI client calls the data plane with a gateway token. It uses provider-compatible request formats rather than the management API.Gateway
A project resource that routes AI requests to configured providers. A gateway can enforce models, rate limits, spend limits, logging, caching, and guardrails without placing the provider credential inside your application.Provider
An AI platform that receives the final model request, such as OpenAI, Anthropic, or Gemini. uses the configured provider credential to make the upstream request on behalf of a gateway.Routing
The gateway rules that select the provider, model, and credential for an incoming AI request. Routing lets an application use one gateway URL while the gateway applies the chosen configuration.Guardrail
A gateway rule that checks or restricts an AI request or response according to the gateway’s policy. Guardrails are configured in the control plane and applied to relevant data-plane traffic.Rate limit
A maximum number of allowed requests during a period, often requests per minute. may return429 when a control-plane or gateway limit is reached.
Spend limit
A maximum allowed AI-provider cost for a gateway or period. It helps prevent unexpected usage. A request can be rejected when the configured spend limit has already been reached.Usage data
Information about gateway traffic, such as request count, tokens, latency, and spend. It is used to understand how a gateway is being used.Request log
A record of a gateway request and its outcome. Reading request or response bodies can expose sensitive content, so it requires the dedicatedusage:read-bodies permission.
OpenTelemetry (OTel)
A standard format for application telemetry. can export gateway metrics and traces to an OTel destination. Stored export header values are write-only and are not returned later.Developer tools and audit
REST API
The HTTPS interface documented in API Reference. Use it when you need direct HTTP control-plane requests or when your platform does not use TypeScript.Software Development Kit (SDK)
A Software Development Kit (SDK) is a package of code that lets an application use another product.@airctrl/sdk is ‘s TypeScript SDK. It wraps the public API and performs the local
cryptographic work needed for record values. Use it inside an application, server, or script.
Command-Line Interface (CLI)
A Command-Line Interface (CLI) is a program you control by typing commands in a terminal. Theairctrl CLI works in a terminal, CI job, or local development workflow. Its airctrl run command
injects record values into one child process without creating a .env file.
Model Context Protocol (MCP)
Model Context Protocol (MCP) is a standard way for an AI application to call tools from another service. The MCP server runs locally or in your own environment and lets an AI agent use approved capabilities. It is not a hosted agent and it does not make an agent automatically trustworthy with secret values.MCP tool
One operation exposed by the MCP server, such as listing projects or reading a record. You can ask an agent in natural language; you do not need to know the tool’s internal name. Documentation shows the name only as a technical reference.Audit event
A security-relevant record of an action, such as creating, sharing, reading, or changing a resource. Audit events help explain what happened without exposing the underlying secret value.Audit chain
The linked history used to detect whether audit events were changed or removed. Each event is tied to the previous event, making unexpected changes visible during verification.Health state
The operational state derives from a record’s due date:healthy, expiring, critical, or
expired. It helps teams find credentials that need attention before they cause an outage.