API keys

An API key authenticates every call your team makes to the Impello API. Calls to a sandbox itself carry a sandbox-scoped access token that the SDK attaches for you (see Network and Filesystem).

Where to find your key

Keys are created and read at dashboard.impello.ai/keys. That page is the only place a key is ever shown.

• A key belongs to the team, not to the person who made it. Every member of the team can see and manage the team's keys.
• A team can hold several keys. Give each one a name of up to 64 characters, and rename it later if you want.
• The full key is shown once, when it is created. Impello stores a hash of it, so a key you did not copy cannot be recovered, only replaced.
• The keys page lists every key the team created, with its name, a masked value, when it was created and when it was last used. The reserved dashboard-session key that keeps your browser signed in is hidden, and cannot be renamed or deleted there.
• A key carries no expiry date: the keys page records only when it was created and when it was last used.

Set it once

Export the key as IMPELLO_API_KEY and both SDKs pick it up. Nothing else on this page is required.

export IMPELLO_API_KEY=imp_...

import { Sandbox } from '@impello/sdk'

const sandbox = await Sandbox.create('base')
const result = await sandbox.commands.run('echo hello')
console.log(result.stdout)

await sandbox.kill()

Over HTTP the key travels in the X-API-KEY header. The base URL is https://api.sandbox.impello.ai.

Pass it per call

Every call that reaches the API also accepts the key as an option. A key passed this way wins over the environment variable.

import { Sandbox } from '@impello/sdk'

const sandbox = await Sandbox.create('base', {
  apiKey: process.env.TEAM_A_KEY,
})

const paginator = Sandbox.list({ apiKey: process.env.TEAM_B_KEY })
const sandboxes = await paginator.nextItems()

In Python you can bind the key to a client once and use client.Sandbox and client.AsyncSandbox in place of the top-level classes. A parameter passed to a single call beats the client, and the client beats the environment. The TypeScript SDK has no client class; pass apiKey per call instead.

import os

from impello import Impello

client = Impello(api_key=os.environ["TEAM_A_KEY"])
sandbox = client.Sandbox.create("base")

What a key can do

A key acts for the whole team. It can create, connect to, list, pause, resume and kill the team's sandboxes, read their logs and metrics, change their network rules, and build, list and delete the team's templates. It cannot read, create, rename or delete API keys; the API refuses that route to a team key, and those operations live in the dashboard, behind your login.

Revoke and rotate

Delete a key on the keys page to revoke it. The deletion cannot be undone, and anything still using that key is refused.

To rotate a key without downtime:

1. Create a new key on the keys page.
2. Set IMPELLO_API_KEY to the new value everywhere the old one is used, and redeploy.
3. Delete the old key. Its "last used" column tells you whether anything is still on it.

Key format

A key is imp_ followed by hexadecimal characters. Both SDKs check the shape before sending a request, and the two checks are not the same. The Python SDK requires imp_ plus hex and raises AuthenticationException on anything else. The TypeScript SDK is looser: it also accepts the older prefix, and raises AuthenticationError only when the key is not shaped like a key at all. Neither check decides whether the key is a valid one; that is the API's answer.

A missing key raises the same error type, with a message pointing at the API Keys tab on the dashboard. The TypeScript message still names the older environment variable and shows an old-prefix example key — set IMPELLO_API_KEY to an imp_ key. A key the API rejects comes back as HTTP 401, which the SDKs raise as AuthenticationError or AuthenticationException with the message Unauthorized, please check your credentials. — Python prefixes it with 401: . See Errors.

The TypeScript SDK can skip the shape check: pass validateApiKey: false or set IMPELLO_VALIDATE_API_KEY=false. The Python SDK always checks; its validate_api_key parameter is deprecated and has no effect.

A key minted before Impello moved to its own prefix cannot be made to work by any client, and the two SDKs say so at different moments. Python refuses it locally, raising AuthenticationException with a message naming the 2026-08-30 cutover. TypeScript lets it through the shape check, so the request goes out and comes back as HTTP 401. Replace the key on the keys page; see Migrate.

Other settings

Each setting is read from the environment under its IMPELLO_ name. The older prefix is still read as a fallback, so an existing environment keeps working — see Migrate.

Most of these settings, and a few that have no environment variable, can be passed on any call that reaches the API: Sandbox.create, Sandbox.connect, Sandbox.list, Sandbox.kill and the rest. Where a TypeScript option is narrower than that, the table says so.

requestTimeoutMs is milliseconds in TypeScript and request_timeout is seconds in Python; 0 disables the request timeout in both. Neither bounds the sandbox's own lifetime — that is timeoutMs or timeout on create, covered in Timeouts.

Logging is a separate option rather than a variable. Pass logger to Sandbox.create or Sandbox.connect, and the sandbox keeps using it for every later request. In TypeScript it accepts anything shaped like console; in Python it is a standard library logging.Logger. Without one, neither SDK logs requests.

The TypeScript SDK also reads IMPELLO_ACCESS_TOKEN into a deprecated accessToken option, and sends it as a bearer token. An API key is the only credential you need; leave it unset. The Python SDK does not read it at all.

Next: Templates.