endor-auth-setup

name	endor-auth-setup
description	Use when probing, verifying, or refreshing Endor Labs SDK credentials before API workflows—env-key scan, Client whoami check, endorctl detection, and interactive browser token refresh into .env. Step zero for any tenant session. Not for SSO policy mapping or AuthenticationLog RCA.

Authentication setup

Step-zero playbook for SDK, endorctl, and MCP consumers. Normative env rules live in errors-and-auth.

see README.md.

• Not for CI: browser refresh opens localhost:30000 and requires a human present.

Environment variables (Tier A — ongoing sessions)

Variable	When to set	endorctl flag	SDK / endor-auth
ENDOR_TOKEN	After browser refresh	--token	Yes
ENDOR_API_CREDENTIALS_KEY + SECRET	CI / automation	--api-key / --api-secret	Yes
ENDOR_NAMESPACE	Tenant-scoped work; SSO tenant root (<tenant>.<child> → <tenant>)	-n / --namespace	Yes
ENDOR_API	Non-default API host	-a / --api	Yes
ENDOR_CONFIG_PATH	Non-default endorctl config dir	--config-path	Yes (namespace fallback)

SSO tenant precedence (refresh + reauth): endor-auth refresh -n → ENDOR_NAMESPACE (shell, then .env) → ENDOR_NAMESPACE in endorctl config.yaml (via ENDOR_CONFIG_PATH).

Single auth mode: never set ENDOR_TOKEN and both API key vars (same rule as endorctl). No ENDOR_AUTH_MODE env — unset one credential set or pass auth_method= to Client(...) in code.

Do not document or invent: ENDOR_AUTH_TENANT, ENDOR_AUTH_MODE, ENDOR_AUTH_METHOD, ENDOR_BROWSER, ENDOR_AUTH_INTERACTIVE, ENDOR_AUTH_PERSIST_TOKEN, ENDOR_TOKEN_REFRESH_METHOD.

endorctl init env vars (Tier B — init-time only)

Variable	Flag	Use
ENDOR_INIT_AUTH_MODE	--auth-mode	Exact endorctl enum: github, google, gitlab, azureadv2, sso, browser-auth
ENDOR_INIT_AUTH_TENANT	--auth-tenant	Required for sso
ENDOR_INIT_AUTH_EMAIL	--auth-email	Email-link login
ENDOR_INIT_HEADLESS_MODE	--headless-mode	Headless init

These apply only while running endorctl init. They are not read by endor-auth refresh or Client() for day-to-day API work. After init, use Tier A vars (or config file).

Quick start

# Probe when unsure whether creds work (no secret output)
uv run endor-auth check --tenant <namespace>

# If missing or expired — interactive browser into .env
# (prints whoami + TTL on success; errors on stderr / error logs — no token)
#    SSO (tenant required):  --method sso -n <tenant>
#    Google / GitHub / GitLab / email:
#      --method google | github | gitlab | email --email <addr>
uv run endor-auth refresh --method sso -n <tenant>

# Then run workflows with --env-file
uv run --env-file .env …

JSON probe for agents:

uv run endor-auth check --tenant <namespace> --json

Fields include auth_mode_resolved, sso_tenant_resolved, browser_auth_method_resolved, and whoami.expires_in_seconds.

CLI (endor-auth)

Subcommand	Purpose
check	Scan env keys (booleans only), probe endorctl, run Client().whoami() when creds exist
refresh	Browser OAuth → upsert ENDOR_TOKEN; prints whoami + TTL (never the token)

endor-auth check

Flag	Default	Meaning
--tenant	unset	Pass to Client(tenant=…); falls back to ENDOR_NAMESPACE / endorctl config
--json	off	Structured summary (status, environment, endorctl, whoami, next_steps, auth_mode_resolved, sso_tenant_resolved)

Exit 0 when status=ready; 1 otherwise.

endor-auth refresh

Flag	Default	Meaning
--env-file	.env	Dotenv path to create or update
--method	sso	Documented: sso (requires -n / ENDOR_NAMESPACE), google, github, gitlab, email (requires --email). Other values are experimental — see errors-and-auth.
-n / --namespace	unset	Required for sso (tenant root). Fallback: ENDOR_NAMESPACE, dotenv, ~/.endorctl/config.yaml
--email	unset	Required when --method=email
--environment	from ENDOR_API	API host segment for auth URLs
--timeout	120	OAuth callback wait (seconds)

Does not print the token. On success prints whoami / auth_source / expires_in to stdout and confirms the dotenv update on stderr. Validation failures raise and are logged at error level.

endorctl entrypoint

endorctl init --auth-mode=sso --auth-tenant=<tenant>

Persists credentials and namespace under ~/.endorctl/ (or ENDOR_CONFIG_PATH).

Library

verify_auth bundles scan_auth_env, probe_endorctl, and Client().whoami(). Call pieces separately when you only need env or endorctl probes.

from endorlabs.workflows.auth import (
    scan_auth_env,
    verify_auth,
    refresh_token_to_dotenv,
    probe_endorctl,
)

scan = scan_auth_env()
result = verify_auth(tenant="<namespace>")
endorctl = probe_endorctl()

Decision tree

Situation	Action
dual_mode_conflict	Unset ENDOR_TOKEN or both API key env vars — errors-and-auth
No creds, endorctl on PATH	endorctl init --auth-mode=sso --auth-tenant=<tenant> (persists to ~/.endorctl/config.yaml)
No creds, SDK-only	API key in .env or endor-auth refresh --method sso -n <tenant>
Bearer without ENDOR_NAMESPACE	Set ENDOR_NAMESPACE or pass -n / --tenant
whoami fails / 401	endor-auth refresh (token expired)
whoami fails / 403	Wrong tenant or insufficient scope — fix ENDOR_NAMESPACE / credential access
Creds OK	Proceed to task skills (endor-retrieve-scan-results, …) with uv run --env-file .env

Single auth mode: SDK, endorctl, and MCP must not mix bearer token and API key in the same environment.

.env primer

ENDOR_TOKEN=...
ENDOR_NAMESPACE=<tenant.namespace>

Use one credential mode per file (bearer or API key pair).

API key alternative (CI / automation)

ENDOR_API_CREDENTIALS_KEY=...
ENDOR_API_CREDENTIALS_SECRET=...
ENDOR_NAMESPACE=<tenant.namespace>

Verify: uv run --env-file .env endor-auth check.

Harness matrix

Harness	Auth behavior
Human local	endor-auth refresh (whoami on stdout) then uv run --env-file .env workflows
Agent / sandbox (no browser)	Run endor-auth check; output endor-auth refresh for human — do not open browser
Long scripted session	One Client instance; bearer sessions warn before expiry, then raise UnauthorizedError when expired
Persist token	Only endor-auth refresh — Client never writes refreshed bearer state to disk

Expired token mid-session

• In-memory only: one Client instance holds the bearer until it expires; no .env or os.environ writes.
• Proactive: when expiry is within 30 minutes, Client prints a one-time stderr warning (no token values) with the matching endor-auth refresh --method … command; endor-auth check --json also exposes expires_in_seconds.
• Expired / 401: bearer auth fails closed with UnauthorizedError; rerun endor-auth refresh before continuing.
• Next process: run endor-auth refresh (or pass token= again) — child shells do not inherit in-memory tokens.

Related skills

Need	Skill
SSO / login RCA	endor-troubleshoot-authlog
SDK list / traverse errors	endor-troubleshoot-sdk
Auth workflow reports	endor-workflow-reports