Sign in for the CLI and local tools, use an API key everywhere else, and send it the right way for each surface.
There are two ways to prove who you are to Expand.
| Use | When |
|---|---|
Sign in with expandai login | Your own machine. The CLI and a local MCP server reuse the session, and there is no key to manage. |
| An API key | CI, servers, scripts, the TypeScript SDK, direct API calls, and MCP clients that cannot sign in. |
Sign in once and the CLI keeps the session on your machine:
expandai login
expandai whoamiexpandai login offers two choices: open the browser and approve, or paste an API key. expandai whoami shows your account, organization, and how you are authenticated. expandai logout clears the stored credentials.
A local MCP server started with expandai mcp run uses the same stored credentials as the CLI, so no API key goes into your agent's config. The hosted MCP server signs you in through the browser instead. See Connect your agent (MCP).
Create a key in the dashboard. Keys start with xpnd_.
The CLI, the TypeScript SDK, and direct API calls all read EXPAND_API_KEY:
export EXPAND_API_KEY="xpnd_..."How the key travels depends on where you call Expand:
| Surface | How the key is sent |
|---|---|
| HTTP API | The x-expand-api-key header. |
| TypeScript SDK | new ExpandClient() reads EXPAND_API_KEY and sends it as x-expand-api-key. Pass apiKey only when the key comes from somewhere else. |
| CLI | EXPAND_API_KEY is used when there is no stored sign-in. |
import { ExpandClient } from '@expandai/sdk'
const expand = new ExpandClient()
const markdown = await expand.fetch({ url: 'https://news.ycombinator.com' })# The key is used when there is no stored sign-in.
expandai fetch https://news.ycombinator.comcurl https://api.expand.ai/v1/fetch \
-H "x-expand-api-key: $EXPAND_API_KEY" \
expandai login takes precedence over EXPAND_API_KEY. To use the key on a machine where you have signed in, run expandai logout first.For an MCP client with no browser sign-in, send the key as a bearer token:
{
"mcpServers": {
"expand": {
"url": "https://api.expand.ai/v1/mcp",
"headers": {
"Authorization": "Bearer xpnd_your_api_key"
}
}
}
}EXPAND_API_KEY is the only setting most setups need. The CLI's other environment variables and its config file location are on CLI: Commands, Environment and config.
| Hosted MCP server | Authorization: Bearer xpnd_... in the client config. |