This guide covers how pai picks the Phantom AI key a command spends, which commands need no key, and what rotate and burn do to a saved copy.
pai looks in three places and takes the first one it finds ( keySource, resolveApiKey):
PHANTOM_KEY_NAME: the key saved under that name with pai keys save or pai buy --card --save. If no key has that name, the command stops with No saved key named <name>.PHANTOM_API_KEY: the key itself, from the environment.pai login saved.With none of them, a command that needs a key stops with No API key. Set PHANTOM_API_KEY or run: pai login.
A saved name beats PHANTOM_API_KEY on purpose:
export PHANTOM_API_KEY=sk-phantom-... # default key
PHANTOM_KEY_NAME=worker pai claude # this agent runs as the saved key "worker"
pai key show with no name prints the key pai would use by these rules. pai setup relies on that: Claude Code runs pai key show to get its key, and the shell block setup writes for other agents runs it too, so a later login or rotate carries over. See Setting up coding agents.
pai login # connect a workspace by device approval
pai login --paste # validate and save an existing key
pai logout # forget local workspace access and default key
pai keys save <name> [key] # validate and save another key by name
pai keys saved [--balance] # local saved names and IDs
pai keys show [name] # print a secret for shell integration only
pai keys rm <name> # forget a copy; the remote key keeps working
login --paste and keys save refuse anything that doesn't start with sk-phantom-, and ask Phantom AI for the key's balance before saving, so a dead key never gets saved. keys save refuses a name that is already taken.
Names use letters, numbers, - and _, start with a letter or number, and run up to 32 characters. The id next to each name is the start of the key's SHA-256 hash ( keyId).
The login key lives in the file key in the state folder, and named keys in keys/<name>. On macOS those files hold a pointer to the Keychain. See Saved secrets.
Pai does not resolve an inference key before key, keys, workspace,
login, logout, setup, or verify --receipt. Workspace operations instead
use saved management credentials; local saved-key operations need no workspace.
Agent commands resolve their key or MPP payment source themselves.
--help, --version and mcp also start without a key.
pai rotate asks Phantom AI for a new key and retires the one the command ran as ( rotateKey). The old key stops working, so pai writes the new key where the old one was saved:
| The command ran as | After rotate |
|---|---|
a named key (PHANTOM_KEY_NAME) |
the new key replaces keys/<name>; the output names it in saved_to and leaves the key out |
| the login key | the new key replaces the login key |
PHANTOM_API_KEY, holding the login key (as pai setup's shell block sets it) |
the new key replaces the login key |
PHANTOM_API_KEY, holding any other key |
nothing is saved; the output prints the new key, and you update the variable yourself |
pai burn revokes a key ( burnKey). Any credit left on it is forfeited: the output shows the amount in forfeited_usd, and pai moves it nowhere.
pai burn # the key this command runs as
pai burn --key-name worker # a saved key, by name
After the key is revoked, pai deletes the saved copy it came from: keys/<name> for a named key, the login key for the login key. A key from PHANTOM_API_KEY that matches the login key deletes the login key too; any other key from PHANTOM_API_KEY has no saved copy to delete.
pai mcp starts without a key and lists its tools ( createMcpServer). Each tool that calls Phantom AI picks the key when you call it, by the same order as above. A missing key comes back as a tool error. The environment is the one the server started with, while the saved files are read on every call, so a pai login after the server starts takes effect on the next call.
These tools need no key: list_saved_keys and verify_receipt.
delete_key signs in as the key it deletes, which is how Phantom AI revokes a key. Pass key_name (a saved key, whose saved copy pai then deletes) or api_key. It refuses the key the server itself runs as; use pai burn for that one.