| 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
uv run endor-auth check --tenant <namespace>
uv run endor-auth refresh --method sso -n <tenant>
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
