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.
endorlabs	{"catalog":{"workflow_id":"auth-setup","module":"endorlabs.workflows.auth.cli","cli":"endor-auth","agent_visible":true,"library_entrypoints":["endorlabs.workflows.auth.scan_auth_env","endorlabs.workflows.auth.verify_auth","endorlabs.workflows.auth.refresh_token_to_dotenv","endorlabs.workflows.auth.probe_endorctl"]}}

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