API keys

Every call to Telem needs an API key. You create keys in the Telem console, in a project, and you can show a key again whenever you need it.

Sign in

Sign in to the Telem console with Google or GitHub. Your first sign-in creates your account, with an organization and a project. You are the Organization administrator and the project’s Project Maintainer, so you can create keys right away.

Create a key

1. Open your project, then API keys in the sidebar.

2. Select Issue API key. Give the key a name, and tick the services it may call. Leave Expires empty for a key that does not expire.

3. Select Issue key, then copy the key. Telem keys start with tlm_. You do not need to write the key down: you can show it again later.

Service	What a key with it can do
Telem Search	Search, read pages and run monitors. Every key that searches needs it.
Telem Data	Read sessions and results back, for example client.sessions.history() or GET /v1/interactions. A key without it can still read the session history of a monitor it created.
Telem Compute	Run and read benchmarks.
Telem Admin	Project administration. Leave it off unless you need it.

You can change a key’s services later only through the API, not in the console. Issue a new key instead.

Who can create keys. The Organization administrator, in every project of the organization, and a Project Maintainer, in that project. A Project Editor or Project Viewer sees the list of keys, but cannot create, show or revoke them.

Show a key again

In the list, select Reveal on an active key, then Copy. Telem records every reveal in the project’s audit log. You cannot reveal a key after it is revoked or expired.

Rotate a key

The console has no rotate button. You rotate a key by issuing a new one, then revoking the old one:

1. Issue a new key with the same services.

2. Put the new key where the old one is used: TELEM_API_KEY, your code, and each agent. To change it for the integrations, run the installer again.

3. Revoke the old key. In the list, open the key’s menu, select Revoke, then Revoke key.

A revoked key stops working within a few seconds. Revoking cannot be undone: the key stays in the list as revoked. A key with an Expires date stops working on that date in the same way, and cannot be brought back either. To set or change the date of an active key, use Rename or set expiry in its menu.

The call	The answer
No key	401 {"detail": "Missing API key"}
A revoked, expired or unknown key	401 {"detail": "Invalid API key"}
A key without the service for this call	403 {"detail": "API key is not authorized"}

Keys that sign-in creates

Claude, ChatGPT and other MCP clients can sign in with your Telem account instead of using a key that you copy. When you select Allow, Telem creates a key for that client in the project that you pick. Its name starts with MCP: and the client’s address, such as MCP: claude.ai. It has Telem Search and Telem Data, and it expires after 90 days. The client never sees the key.

To disconnect the client, revoke its key. Its calls stop within about 5 minutes. Each new connection creates another key, and an old one stays until it expires.

Use your key

Set it once as an environment variable:

export TELEM_API_KEY=tlm_your_key

Every request then sends it in this header:

Authorization: Bearer tlm_your_key

The SDKs and most plugins read the key from the environment. Claude Code, Codex, Grok Build, Muse, VS Code, Cursor and Devin Desktop keep their own copy of the key: see Resolution order.

TELEM_API_KEY

Your API key. Every request sends it as an Authorization: Bearer <key> header.

A key belongs to one project and has its own grant for each service. So a key reaches only the services of its project.

A request without a key gets 401 {"detail": "Missing API key"}. If the key is not set, the client does not raise an error. It sends the request without an Authorization header, and you get that 401.

TELEM_BASE_URL

The deployment to call. The default is the hosted deployment, https://router.telem.ai. Set it, or pass base_url in code, to call a staging or self-hosted deployment.

The SDKs and the plugins have this default. A plain curl command has none: export the variable, or the request fails with curl: (3) URL rejected.

Resolution order

Each setting takes the first value it finds, in this order:

1. An argument in code: Telem(api_key=..., base_url=...), or the same value in the config of a surface, such as an OpenClaw plugin config entry.
2. An environment variable: TELEM_API_KEY or TELEM_BASE_URL.
3. The credentials file: ~/.telem/credentials.json (mode 0600). The installer writes it: the one-line curl or npm create @telemai. TELEM_CONFIG_DIR moves it. These read it:
   • the Python SDK and everything built on it;
   • the JavaScript SDK on Node 20.16 or later;
   • the OpenCode, Pi, OpenClaw and DeepSeek Harness plugins.
4. The default: none for TELEM_API_KEY, so no Authorization header is sent. https://router.telem.ai for TELEM_BASE_URL.

Claude Code, Codex, Grok Build, Muse, VS Code, Cursor and Devin Desktop do not read the credentials file. When you pick them, the installer also writes the key into their own config: ~/.claude/settings.json for Claude Code, ~/.codex/config.toml for Codex, ~/.grok/config.toml for Grok Build, ~/.config/muse/settings.json for Muse, ~/.copilot/mcp-config.json for VS Code, ~/.cursor/mcp.json for Cursor and ~/.config/devin/mcp_config.json for Devin Desktop. To change the key for them, run the installer with --login: it gives the new key to each of them. Without --login, the installer keeps the key that you saved before, as long as it works.

These seven reach Telem through its MCP server, https://mcp.telem.ai/mcp. A private deployment has its own MCP endpoint: install with --mcp-url and its full url, next to --base-url. The installer points each of the seven that it installs at it, and saves it in the credentials file as mcpUrl, so a later run, --login included, keeps it. Claude Code is the exception when its telem marketplace came from GitHub: that plugin keeps https://mcp.telem.ai/mcp, and the installer warns.

Credentials are never .telem/telem.json keys: that file holds options. OpenClaw is the exception. Its host config has apiKey and baseUrl.

Keeping your key safe

• Set it as an environment variable, or in a .env-style file that is not in version control: ~/.openclaw/.env for OpenClaw, your shell profile for local SDK use.
• Prefer the environment to a plain-text config file when a surface reads both.
• If a key is shared by accident, revoke it, and issue a new one.

Next steps

• Quickstart: run your first search with your key
• Errors: what a 401 or a 403 means
• Parameters: the options in .telem/telem.json