Your Credentials

Onboarding to Alter creates a few credentials. Alter shows each secret to you once, when it is created, and keeps only a one-way hash of it afterwards. Alter cannot show a secret again or recover a lost one. Keeping each secret safe, and replacing it when needed, is your responsibility.

This page lists every credential you will meet, where it ends up, and what to do with it.

At a glance

Credential	Looks like	Created by	Where it lives	Your job
CLI access token (PAT)	alter_pat_…	alter auth login	Your OS keychain, stored by the CLI (see below)	Nothing on your laptop; in CI, keep it in the CI secret store as ALTER_PAT
App runtime key	alter_rk_…	Portal API Keys → Create key, or alter keys mint	Only where you put it	Store it as ALTER_API_KEY in a secret manager or a git-ignored .env; rotate before it expires
Agent key	alter_key_… (per-agent keys still use this legacy prefix)	alter agents create, or alter agents mint-key	Only where you put it	Store it as AGENT_API_KEY where the agent process reads it

None of these belong in source code, a committed file, a chat with a coding agent, a log line, or a screenshot.

CLI access token (PAT)

alter auth login creates a personal access token for the alter CLI and stores it for you. It lets the CLI manage your app (create keys, configure providers, read the audit log). It is not used by your application.

The CLI looks for the token in this order:

1. The ALTER_PAT environment variable. This is how CI and headless hosts supply it.
2. Your OS keychain: macOS Keychain, Linux Secret Service / gnome-keyring, or Windows Credential Manager. An interactive login saves it here by default.
3. A fallback file, ~/.config/alter/auth.toml (or $XDG_CONFIG_HOME/alter/auth.toml), readable only by you. The CLI uses it only when the keychain is unavailable, and prints a warning each time it saves there. To use the keychain instead, see Credential storage.

What you need to do:

• On your own machine: nothing beyond signing in. Check it with alter auth status.
• In CI: create a token in the dashboard (Settings → Personal Access Tokens → New token), store it as a masked ALTER_PAT secret, and let the CI provider inject it. Do not run alter auth login in CI.
• To sign out: alter auth logout removes the local copy only. To stop the token working everywhere, delete it in the dashboard.

App runtime key

Your backend uses this key to call Alter: App(api_key=...) in the SDK. The portal and alter keys mint show it once.

• From the portal: copy the value from the dialog before closing it.

• From the CLI: send the output straight to a file so the key never appears on screen:

  alter keys mint --name my-backend --scopes <scopes> --output json > .alter-key.json

  The secret is the plain_key field. (api_key in that output is the key’s metadata, not the secret.)

Then:

1. Put it in your app’s environment as ALTER_API_KEY: a secret manager in production, or a git-ignored .env file locally.
2. Delete .alter-key.json.
3. Note the expiry. App keys expire under your organization’s key TTL (90 days by default on a new organization). Replace a key before it expires with alter keys rotate --key <key-id> or the portal’s Rotate; the old key keeps working for an overlap window. See API Keys.

Agent key

An AI agent that calls providers under its own identity uses the agent’s own key: Agent(api_key=...) in the SDK. alter agents create returns the agent’s first key, once, in the api_key field of its output:

alter agents create --name research-bot --scopes '<allowlist-json>' \
  --output json > .alter-agent-key.json

Then:

1. Put it where the agent process reads its secrets, as AGENT_API_KEY.
2. Delete .alter-agent-key.json.
3. Mint another key with alter agents mint-key --agent <agent-id> only when you genuinely need one, for example one per process or for a rotation, and revoke keys you no longer use.

Note

An alter_ak_… key from alter keys mint --key-type agent is not an agent key in this sense: it is not linked to any agent, so it cannot use connections delegated to an agent or secrets bound to one. Use the key from alter agents create.

Values that are not long-lived secrets

These appear during onboarding but need different handling:

Value	What it is	Handling
Grant ID	A reference to a stored connection or managed secret	Not a secret on its own; it only works together with a valid key. Fine in configuration and environment variables.
App ID	Your app’s identifier	Not a secret. alter link pins it in .alter/config.yaml and adds .alter/ to .gitignore.
Connect session token	A short-lived, single-use token your backend creates for the Connect popup	Send it to the browser for that one connection; never store it.
Derived key (alter_dk_…)	A short-lived, narrowed key your code creates from an app key	Keep it in memory for the task it was made for.
MCP config (.mcp.json, .cursor/mcp.json)	Tells your coding agent where the Alter Docs MCP server is	Holds no credentials.

Alter stores the provider credentials behind your grants (Google tokens, Datadog keys, and so on). With direct app.request() or agent.request() calls, the SDK retrieves the credential into your application process and injects it into the outgoing provider request. Your code receives the provider response, but the credential briefly exists in that process. Use app.proxy_request() or agent.proxy_request() when the credential must stay outside your application process; Alter injects it in the proxy instead. See Direct requests and proxy mode.

Before you mint anything

Add these lines to your project’s .gitignore first:

.alter-*.json
.env

The CLI’s minting commands only print the secret. Nothing else keeps a copy, so the file you redirect into is the only one until you move the value.

If you use a coding agent

The Alter Docs MCP server walks a coding agent through this same flow. Its instructions tell the agent to:

• redirect every minted key to a git-ignored file rather than printing it;
• never read the key back into the conversation (no cat, no echoing);
• move the value into .env or your secret store, then delete the temporary file;
• tell you which credential was created, where it now lives, and what is left for you to do.

You still own the result. After each key is minted, confirm three things: the secret is not in your chat history or terminal output, the temporary .alter-*.json file is gone, and .env is git-ignored. If an agent ever prints a key, treat that key as leaked.

If a key is lost or leaked

A lost key cannot be recovered, and a leaked one must be replaced:

Credential	Replace it	Cut off the old one
CLI access token	alter auth login	Delete it in the dashboard under Settings → Personal Access Tokens
App runtime key	alter keys rotate --key <key-id> or alter keys mint, or the portal	alter keys revoke --key <key-id>, or Revoke in the portal
Agent key	alter agents mint-key --agent <agent-id>	alter agents revoke-key --agent <agent-id> --key <key-id>, or under Agent Identity → <agent> → API keys

Every call made with a key is recorded in the audit log, so you can check what a leaked key was used for.

What’s next

API Keys

Minting, rotating, and revoking app and agent keys.

CLI authentication

Sign-in flows, CI tokens, and credential storage.

Quickstart

Mint a key and make a first call.