Login, profiles and script tokens

Role: Any account holder. Prerequisites: Installed CLI and the API URL supplied by your service administrator. Browser login also needs the service’s configured OIDC provider. Files: A private profile file; an optional scoped token file for automation.

Sign in

Replace the example origin with the HTTPS origin of your service:

enumeray auth configure https://enumeray.example.org
enumeray auth login
enumeray auth whoami

The login uses authorization code with S256 PKCE and a temporary loopback callback. Complete account onboarding at the identity provider if necessary. Your account is bound to the provider’s issuer and subject, not an email address. whoami shows the account identity and supported operations; retain the user UUID when requesting grants or co-administration.

If the CLI cannot open a browser, use enumeray auth login --no-browser and open the displayed URL in a browser on the same host. The browser must reach the CLI host’s temporary 127.0.0.1 listener. Opening that URL on your laptop does not complete a login running on an SSH/HPC host; use the scoped-token creation and stdin import instructions below for that case.

If registration is enabled, select it when you need a new account and follow the email verification and password screens. Signup must complete within the CLI’s three-minute wait. If the CLI times out, finish provider onboarding and run auth login again. Contact Enumeray support if account onboarding is unavailable.

Saved browser logins renew automatically when a command needs a token near expiry. This includes release, analysis, wait and live-log workflows. Renewal stays within the provider’s existing refresh/offline-session limits; it never opens a browser or asks for input. auth refresh remains available for explicit renewal. Expired or revoked refresh sessions require another auth login.

Existing browser profiles are upgraded when their current access token can still identify the account. If an older profile has already expired, run auth refresh once to enable automatic renewal. Tokens imported with --token-stdin and ENUMERAY_TOKEN have no browser renewal and need replacement through issuance.

Use the updated CLI for an upgraded profile file; older CLI versions may reject its renewal metadata. Do not remove that metadata to retry an interrupted exchange.

The CLI serializes concurrent renewal and saves rotated refresh credentials before checking identity. If an exchange is interrupted after the provider might have consumed a refresh token, the CLI requires another login rather than reusing it. Retain any release/analysis directory or log checkpoint and resume the same operation after login. A permissions error or unexpected authorization rejection stops the command; automatic renewal does not retry it.

auth logout removes local credentials and prevents running commands from adopting another login. It leaves the browser’s provider login and server-side offline tokens active; revoke those through the provider’s account console when needed.

Keep services separate

enumeray --profile research auth configure https://research.example.org
enumeray --profile research auth login
enumeray auth profiles
enumeray --profile research auth whoami

The default profile is default. Profiles are saved atomically with mode 0600 under $XDG_CONFIG_HOME/enumeray/profiles.json, or the platform’s home configuration directory when that variable is unset. --config selects another file. Changing a profile’s origin clears stored credentials. An --api override never reuses a token for another origin.

Create a script token

enumeray auth token-create analysis-script \
  --scopes models:read,runs:create,runs:read,me:read \
  --output token.json
enumeray auth token-list

Add upload/artifact scopes when the script needs files, and runs:cancel when it must cancel work. See the exact scope names. Scope does not replace resource access: a token can only perform operations its account is authorized to perform. The default CLI lifetime is 30 days; --expires-in-seconds selects a supported lifetime.

ENUMERAY_TOKEN supplies a token to noninteractive commands. Supply it through your process’s secret environment rather than placing it in command arguments or shared shell history. enumeray auth login --token-stdin imports a token into a private profile without exposing it in arguments. Do not paste the complete issued token JSON into token stdin; supply its token value.

For example, create a separate script profile and import the saved secret using jq:

enumeray --profile analysis auth configure https://enumeray.example.org
jq -er '.token' token.json | enumeray --profile analysis auth login --token-stdin
enumeray --profile analysis auth whoami
enumeray --profile analysis model list

To run a command directly with that token in its environment, without changing a profile:

ENUMERAY_TOKEN=$(jq -er '.token' token.json) \
  enumeray --api https://enumeray.example.org auth whoami

ENUMERAY_TOKEN takes precedence over the selected profile’s stored token. Remove an unintended exported value with unset ENUMERAY_TOKEN before diagnosing browser-profile permissions. Token stdin login validates the token with me:read, so include that scope when creating tokens for this workflow. A personal token has no browser refresh token: renew it through issuance rather than auth refresh.

Logout removes local tokens. Revoke a personal token on the server with enumeray auth token-revoke TOKEN_UUID; obtain the UUID from the token inventory. A lost token-creation response needs inventory inspection and revocation before you create a replacement.

Expected outcome: auth whoami succeeds for the intended profile and API. Next: Run a model, or follow login troubleshooting if authentication fails.