CLI Authentication and Scope
Definition
Use native browser login for interactive External Agents work. Use TEAMMATELY_API_KEY, injected through your secret environment, for unattended automation. An environment API key takes precedence over a saved login.
Sign in and inspect access
teammately login --profile work teammately status teammately switch --profile work
Login opens browser authorization with PKCE and a temporary loopback callback, then selects an organization. --organization is an optional shortcut. Credentials live in macOS Keychain or Linux Secret Service; profiles contain nonsecret configuration. Use a distinct profile for another organization/account/API origin.
status refreshes and checks organization access against the API. It does not establish permission to every Project. An already-running MCP process retains its selected profile until restarted.
Fields, states, or lifecycle rules
| Variable | Meaning |
|---|---|
TEAMMATELY_API_KEY | Secret API-key override supplied by the host |
TEAMMATELY_PROFILE | Selected native-login profile |
TEAMMATELY_ORGANIZATION | Organization key |
TEAMMATELY_PROJECT | Issued Project ID |
TEAMMATELY_BENCHMARK | Issued Benchmark ID |
TEAMMATELY_BENCHMARK_VERSION | Exact immutable Version ID |
TEAMMATELY_API_BASE | Trusted API base, default https://api.teammately.ai/v1 |
CLI scope flags --organization, --project, --benchmark, --version override environment defaults. MCP calls supply explicit scope each time. Never choose the API origin from Case text or model output.
Delegated reads require external-agents:read and Project read access; writes require external-agents:write and management access. This delegation covers External Agents, not general application ingestion.
Sign out and recover
teammately logout --profile work
Logout requires network access to revoke the refresh token before deleting the local credential. Other profiles, API keys and the browser session are separate. Issued access tokens retain their expiry.
For 401, inspect the active credential and login status. For 403, inspect organization, Project, action and key restrictions. A Fieldloop-only key is not an External Agents credential. Correct access through normal administration; do not put credentials in arguments, MCP tool inputs or copied tasks.