UN-4016 [FEATURE] auth login, flattened platform key, per-deployment keys and key-error UX

[chandrasekharan-zipstack]

Stacked on #3 (UN-4016-platform-key). Four commits, each independently green.

What changes

Platform key flattened — [profiles.X.platform] is gone. The platform key is platform_key on the docstudio block (api_key there stays the deployment key); $UNSTRACT_PLATFORM_KEY and env: indirection are unchanged. auth whoami and deployment ls read the docstudio base_url. The explicit_tiers cross-walk and the PLATFORM product are deleted; a discovered .unstract.toml withholds platform_key like any other credential.

Deployment entries slimmed — [profiles.X.deployments."<api_name>"] holds only api_key. deployment run / status take the API name directly, as deployment ls prints it. The key for a run resolves flag > env > per-deployment entry > profile api_key (the entry is specificity within the profile tier, not a tier above the environment), pinned by an ablation test over all four sources. config set docstudio api_key <key> --deployment <api_name> is the write path.

Key-error UX — nothing resolving is a usage error raised before any request, listing every place the CLI looked and the exact remedy for each. A 401/403 is translated to name the deployment, say the supplied key does not authorize it, and give the per-deployment config set … --deployment line (the previously unreachable hint; reachability is tested through both run and status). A 404 points at deployment ls.

Staleness — config doctor --probe, when a platform key resolves, cross-checks deployments entries against the live listing and reports orphans as warnings (stale_deployments in the report, never a failure). Without a platform key the check is skipped silently. Gated under --probe so a bare doctor stays offline.

unstract auth login — at a terminal: one hidden, skippable prompt each for platform, deployment and LLMWhisperer keys, at least one required. Platform key is checked with whoami (organisation stored beside it), LLMWhisperer key against the usage endpoint, deployment key stored as given and reported as such. Every check runs before the single 0600 write; keys are stored as literals. Non-interactive twin: --platform-key / --deployment-key / --llmwhisperer-key, any one of them - for stdin, zero prompts; a bare non-TTY run fails fast (exit 2) naming the flags. Re-run rotates in place. Org-mismatch guard: a profile already holding a different org_id is not repointed silently — interactive offers a new profile named from the organisation's display name, or overwrites on request; non-interactive fails naming both organisations and --force. whoami's profile writer is split into shared pieces rather than duplicated; config init now points new users at auth login.

README — quickstart leads with auth login for humans and an environment-only three-liner for agents/CI; the three credentials are described once, by role and where minted; no [profiles.X.platform], no aliases.

Migration: deployment aliases removed

An entry like

[profiles.cloud-us.deployments.invoices]
api_name = "invoice-parser"
org_id = "org_ABC"
api_key = "env:INVOICES_KEY"

no longer resolves. run invoices sends invoices as the API name. Rename the table to the API name and keep only the key that differs from the profile's:

[profiles.cloud-us.deployments."invoice-parser"]
api_key = "env:INVOICES_KEY"

org_id is per profile; an alias that named a different organisation becomes its own profile. Most users can delete the section entirely and run by API name.

Exit codes (auth login)

Situation	Code
Stored	0
No key given, or non-TTY without flags, or two -	2
A key rejected (nothing written)	3
Profile belongs to another organisation, no --force (non-TTY)	2
Keys accepted, write failed	10

Testing

ruff check, ruff format --check, pytest (481 passed, 1 skipped). Every behavioural change has a test that fails on revert; the two isatty/command-tree guards in the existing suite were updated deliberately (auth login is the one command that asks whether it may prompt — never what it prints in).

🤖 Generated with Claude Code

https://claude.ai/code/session_01J2SKeanczq13ngDQNbgFNL

[greptile-apps]

via Greptile

Confidence Score: 5/5

The PR appears safe to merge; no outstanding correctness, security, or repository-rule issue remains.

Findings

1.   Retained Keys Reach New Host ▶

Fix with agent prompt

### Issue 1
src/unstract_cli/commands/platform_cmd.py:379-384
When the organisation-mismatch flow selects an existing destination profile, this replaces its shared `docstudio.base_url`, but credentials omitted from the current login remain in that profile. For example, logging in with only a platform key retains the destination's existing deployment key and per-deployment entries. Later deployment commands send those retained credentials to the new host even though they belonged to the profile's previous host. Clear incompatible retained credentials, refuse the merge, or otherwise preserve a host and credential combination that the user explicitly selected.

**How this was verified:** The login loop skips omitted credentials while replacing the shared host, and deployment clients subsequently send the retained key to that shared host.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

This PR restructures credential configuration and adds a unified authentication workflow.

• Flattens the platform key into the DocStudio profile and replaces deployment aliases with per-deployment key entries.
• Adds auth login with interactive and non-interactive credential collection, validation, organization-mismatch protection, and atomic persistence.
• Improves deployment-key error messages and adds live stale-deployment checks to config doctor --probe.
• Updates documentation and tests for the revised configuration and authentication model.
• The latest changes fully replace a confirmed destination profile before writing credentials, preventing keys retained from its former host or organization from being sent to the newly selected host.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[auth login] --> B{Keys supplied as flags?}
    B -->|Yes| C[Read flags or one key from stdin]
    B -->|No, terminal| D[Prompt for three optional keys]
    B -->|No, non-terminal| E[Exit with usage error]
    C --> F[Resolve selected profile and hosts]
    D --> F
    F --> G[Validate platform and LLMWhisperer keys]
    G --> H{Organization mismatch?}
    H -->|No| K[Update selected profile]
    H -->|Non-interactive without force| I[Exit with usage error]
    H -->|Interactive: create another profile| J{Destination already exists?}
    J -->|Yes| L[Confirm full replacement]
    J -->|No| M[Create destination profile]
    L --> M
    M --> K
    H -->|Overwrite accepted or forced| K
    K --> N[Perform one 0600 config write]

Loading

_{Reviews (4) · Last reviewed commit: "UN-4016 [FIX] Replace, rather than merge..."}

[greptile-apps]

Retained Keys Reach New Host

When the organisation-mismatch flow selects an existing destination profile, this replaces its shared docstudio.base_url, but credentials omitted from the current login remain in that profile. For example, logging in with only a platform key retains the destination's existing deployment key and per-deployment entries. Later deployment commands send those retained credentials to the new host even though they belonged to the profile's previous host. Clear incompatible retained credentials, refuse the merge, or otherwise preserve a host and credential combination that the user explicitly selected.

How this was verified: The login loop skips omitted credentials while replacing the shared host, and deployment clients subsequently send the retained key to that shared host.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/unstract_cli/commands/platform_cmd.py
Line: 376-381

Comment:
**Retained Keys Reach New Host**

When the organisation-mismatch flow selects an existing destination profile, this replaces its shared `docstudio.base_url`, but credentials omitted from the current login remain in that profile. For example, logging in with only a platform key retains the destination's existing deployment key and per-deployment entries. Later deployment commands send those retained credentials to the new host even though they belonged to the profile's previous host. Clear incompatible retained credentials, refuse the merge, or otherwise preserve a host and credential combination that the user explicitly selected.

**How this was verified:** The login loop skips omitted credentials while replacing the shared host, and deployment clients subsequently send the retained key to that shared host.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[chandrasekharan-zipstack]

Confirmed. Fixed in 5e2a701 by taking the "refuse the merge" option: the profile the guard names is now rebuilt from what this login verified (cfg.profiles[name] = {} before the write), so a stored deployment key and per-deployment entries from the old host do not survive into the new one. Since that is a replacement, _new_profile_name now confirms any existing name, not only one owned by another organisation. Pinned by test_a_profile_chosen_at_the_guard_is_replaced_not_merged_into.