API keys

An API key is a durable token that lets an agent, script, or CI pipeline act on your Helicarrier account without a browser session. Every key:

• authenticates as you — it can never do more than you can, and never touches operator settings;
• is stored hashed — the raw key (it starts with heli_) is shown once at creation, so copy it immediately;
• carries a last-used time and can be revoked at any time, which stops anything using it instantly;
• works the same over the REST API and MCP — send it as an Authorization: Bearer <key> header.

Choose the narrowest scope that does the job. Helicarrier offers three, from broadest to tightest.

Account-wide keys

The default. An account key reaches everything you can in the dashboard, across all your projects.

In Settings → Your account → API keys:

1. Give the key a name (e.g. Claude agent).
2. Optionally check Read-only — the key can view everything but can’t change anything (safe for an agent that only inspects). Leave it unchecked for full control.
3. Click Create key and copy it — it’s shown only once.

Revoke it any time from the same screen.

Project-scoped keys

Scoped to one project — it can operate every service in that project, which makes it ideal for a CI pipeline that deploys several services together.

Open the project’s canvas menu and choose API keys. You grant:

• a permissions matrix — Deployments, Logs, Metrics, Variables, Domains, Settings, each as read or write (write includes read);
• Project structure — create and delete services, and manage environments;
• optionally, an environment restriction — tick specific environments to limit the key to them, or leave all unticked to span every environment.

A project key reaches only that project and only the permissions you granted. Any other project, plus billing, team, and account settings, answer 403 — over the API or through MCP. If you limited it to certain environments, services in the other environments answer 403 too. It can’t delete or transfer the project, and it can’t mint further keys.

Only a project’s owner can create a project key. Keys are listed on the same panel with their permissions and environment scope, and are revoked automatically if the project is deleted.

Service-scoped keys

The tightest scope — a single service and the categories you tick.

Open the service and use its Agents & API tab. Grant the same read/write categories — Deployments, Logs, Metrics, Variables, Domains, Settings — and create the key there.

A service key reaches that one service and those permissions only. Every other service, your other projects, billing, team, and account settings answer 403. It also can’t open a shell, touch a database’s data, or mint further keys. Keys are revoked automatically if the service is deleted.

How scoped keys stay safe

Both project and service keys are enforced by a default-deny allowlist: only the routes their granted categories cover are reachable, and the same check runs over the REST API and through MCP. Anything not explicitly allowed — a shell, a database’s contents, another project, minting more keys — is refused with a 403.

Because a scoped key deliberately can’t list your whole account, it discovers what it is by calling the whoami MCP tool (or reading GET /api/auth/me), which returns its scope, permissions, and any environment restriction.

Note

Treat a key like a password: don’t paste it into shared configs, and revoke it if it may have leaked. A leaked account key exposes your whole account — prefer a project- or service-scoped key for anything that only needs part of it.

Next

• Connect your agent (MCP) — point an MCP client at Helicarrier with a key.
• Deploy triggers — a single-purpose token that only redeploys one service, for CI.