Skip to main content

tetrate agentrouter idp login

Sign in to an OpenID Connect identity provider as a public client, and store the
refresh token in the operating system's credential store: the macOS keychain,
the Secret Service on Linux, or the Windows Credential Manager. When that store
is unavailable, for example on a Linux host with no desktop session, the
command stores the refresh token in a file that only you can read, under the
same directory as the API credentials file, and says so. That file fallback
exists on Linux and macOS only. On Windows a file cannot be made private, so the
command fails when the Credential Manager refuses the refresh token, and the
token command asks the identity provider for a new access token on every run.

On Linux and macOS both commands refuse to run when the idp directory under the
API credentials directory is owned by another user or gives group or other users
any access, or when the profile file is a symbolic link or can be written by
other users, because those users could then change the token endpoint that
receives the refresh token. The login command creates the directory with mode
0700.

Neither command follows a redirect from the identity provider's discovery,
device or token endpoint, because a redirect could send the refresh token to
another address. A redirect makes the command fail with the endpoint and the
status.

By default the command opens a browser and runs the authorization code flow
with PKCE, with a redirect to http://127.0.0.1:<port>/callback. With --device it
prints a URL and a code to enter on another device instead, which works over
SSH. Neither flow prints a token.

The identity provider's application must be a public client that allows the
loopback redirect or the device code flow, and it must issue refresh tokens,
which most providers do only for the offline_access scope.

Usage:
tetrate agentrouter idp login [flags]

Examples:
tetrate agentrouter idp login --issuer https://login.example.com/tenant/v2.0 --client-id 0f1e2d3c --scope api://agent-router/invoke
tetrate agentrouter idp login --device --issuer https://idp.example.com/realms/acme --client-id agent-router-cli

Flags:
--client-id string client ID of the public application registered for this CLI
--device use the device code flow instead of a browser on this machine
--issuer string issuer URL of the identity provider, as its discovery document names it
--port int loopback port for the browser callback (0 picks a free port)
--profile string name under which to store this sign-in (default "default")
--scope strings scope to request, in addition to openid and offline_access (repeatable)

Global Flags:
-q, --quiet Suppress progress output; only errors and the final summary go to stderr
-v, --verbose Verbose output: plain-mode progress lines plus full per-blob chunk logs to stderr