Authentication

Every request in this reference uses a Bearer token. Create an API key from the dashboard and store it in your local environment or CI secret store.

Authorization: Bearer <YOUR_API_KEY>

The examples read the key from HELI_API_KEY. Run them on your machine or server; keep credentials out of frontend bundles, URLs, shared logs, and source control.

Choose the narrowest useful key

Key type	Best for	Boundary
Service	Deploying one service or reading its logs	One service, with explicit capability categories
Project	Automating a connected application	One project, with optional environment restrictions
Account	Workflows that need account-level operations	The creating user’s access; read-only keys cannot mutate resources

A project or service key is not a smaller account key with every operation enabled. Scoped keys use an explicit set of allowed routes and capability categories. Check Authorization on the operation page before choosing a key.

Create and manage API keys in the dashboard.

Identify the key before using it

Start with a read that does not change any resources:

curl --fail-with-body \
  'https://app.helicarrier.xyz/api/auth/me' \
  -H "Authorization: Bearer $HELI_API_KEY"

A service or project key includes keyScope in this response. An account key does not include that object. For example, selected fields from a service-key response look like:

{
  "keyScope": {
    "kind": "service",
    "serviceId": "svc_example",
    "permissions": {
      "deployments": "write",
      "logs": "read"
    }
  }
}

Use the returned identifier in subsequent calls. A service key cannot list all projects to discover other resources.

Capability categories

Each category is granted at read or write level. A write grant also permits reads in that category.

Category	Typical operations
deployments	Deployment history, deploy, rollback, stop, and abort
logs	Runtime and build logs
metrics	Service resource metrics
variables	Environment variables and service references
domains	Custom domains, exposed HTTP ports, and DNS targets
settings	Build settings, plans, scaling, and schedules
project	Project-key operations that create, delete, or restore services

Database credentials, SQL access, and backups require an appropriately authorized account key. A service’s settings grant does not include these operations.

Environment restrictions

A project key can be limited to selected environments. It cannot reach resources outside that set, even if they belong to the same project.

When creating a service or database, send environmentSlug explicitly. When creating a service from an upload, select the environment with ?env=. Omitting the selection can cause a restricted key to be refused.

Diagnose an authorization failure

• 401: Check the header, environment variable, and whether the key has been revoked.
• 403: Check the key type, capability, resource, and environment restrictions.
• 404: Check the identifier and access. A resource outside your permissions may be reported as missing.

A successful key lookup is not a grant to execute every operation. Both key scope and the creator’s permissions apply to each request.

Rotate or revoke a key

Create a replacement with the permissions the workflow needs, update your secret store, verify it with a read request, and then revoke the old key from the dashboard. If a key has been exposed, revoke it immediately and replace it in affected integrations.

MCP clients can connect using OAuth or an API key. See Connect an MCP client for setup.