Skip to main content
The auth command group handles SSO authentication: log in through the browser and store short-lived STS credentials or only the user’s OIDC session, clear the session, show the current identity, manage login profiles, and prepare CLI SSO login resources for an organization. login, logout, and whoami are also available as top-level commands (e.g. agentkit login).

​
auth login

Authenticate through browser SSO. The default mode exchanges the OIDC login result for short-lived STS credentials. --identity-only stores only the user’s OIDC session, allowing harness invoke to automatically forward the user id_token to a matching custom_jwt Runtime, but it does not create AgentKit management credentials. Generic invoke run calls to a custom_jwt Runtime still need an explicit Authorization header through --headers.

​
Login addresses and discovery documents

When [address] is provided, the CLI reads the login discovery document from /.well-known/agentkit-cli under that address. You may omit https://; production remote addresses must use HTTPS, while only local test addresses may use http://localhost, http://127.0.0.1, or http://[::1]. The address must not contain a username, password, query string, or fragment. For a shared login domain, append one tenant path segment, such as https://login.example.com/team-a; the path must be a single lowercase slug, without nested paths, traversal, or encoded path separators. Remote discovery must return a JSON object directly, without redirects, and the response body must not exceed 64 KiB. Custom tenant addresses allow only these discovery-document fields:
Identity-only login does not provide control-plane permissions. To resolve Runtimes, manage resources, or query projects, configure AK/SK separately or use regular agentkit login to obtain STS credentials. When logging in through a remote discovery document, the CLI saves the discovered profile only after browser login and subsequent credential handling succeed.

​
auth logout

Clear the stored SSO session (refresh token + cached STS credentials).

​
auth whoami

Show the identity behind the current credentials.

​
auth profile set

Create or update a profile’s login coordinates (non-secret).
Login state is stored under ~/.agentkit/auth. The long-lived refresh token is written to the OS keyring when available; when the keyring is unavailable, session files are written locally with 0600 permissions. Identity-only sessions do not retain the OAuth access token, and the CLI never prints stored tokens.

​
auth profile list

List saved profiles. This command takes no arguments or options.

​
auth profile show

Show a profile’s coordinates.
auth admin subcommands require cloud credentials that can manage Identity, IAM, and TOS resources. You can provide AK/SK credentials, or use valid STS credentials from the current CLI SSO profile. To keep privileged setup predictable, auth admin uses built-in service endpoints instead of project or user-wide endpoint overrides.

​
auth admin doctor

Run read-only checks that determine whether the account is ready for CLI SSO setup, including identity permissions and credential-hosting prerequisites. Failed checks produce a nonzero exit code and remediation guidance.

​
auth admin create-userpool

Create a user pool for CLI SSO login and output its ID as JSON.
This command creates an identity resource in the selected account and region. Run auth admin doctor first to check the account, region, and permissions.

​
auth admin provision

Create or reuse a public CLI client, IAM OIDC provider, and STS role for an existing user pool, then output the login discovery configuration.
This command modifies user-pool and IAM resources. Confirm that the user pool belongs to the target account and region, and grant the role only the permissions required by CLI users.

​
auth admin sso-setup

Prepare the user pool, public CLI client, IAM OIDC provider, STS role, and TOS-hosted login discovery document in one flow. The command prints an agentkit login <address> address that can be distributed to CLI users. In an interactive terminal it asks whether to reuse a user pool, configure an upstream identity provider, and use a custom domain. Non-interactive runs use defaults or explicit flags.
This command creates or modifies identity, IAM, and TOS resources and publishes a publicly accessible login discovery document. An upstream identity provider secret is sensitive. Prefer entering it through the hidden interactive prompt instead of saving it in a repository or shell history.
When --domain is set, the command reads the discovery document back through that HTTPS domain and verifies its content after publishing. Configure the CNAME and certificate first; if public verification fails, the command does not print the custom domain as the final login address.

​
auth admin publish

Create or reuse the CLI login resources for an existing user pool and publish the /.well-known/agentkit-cli discovery document to a selected TOS bucket. You can also pass existing OIDC and IAM coordinates to publish only the discovery document, without creating the CLI client, OIDC provider, or role again.
Without explicit coordinates, this command modifies identity and IAM resources and writes public login configuration to the selected bucket. Confirm that the bucket, account, user pool, and explicit coordinates all belong to the target environment; configure the CNAME and HTTPS certificate before using --domain.
Publish-only mode requires --issuer, --client-id, --role-trn, and --provider-trn together. --issuer must be an HTTPS URL without username, password, query string, or fragment; --role-trn and --provider-trn must belong to the currently authenticated account. --bucket must be a TOS bucket name with 3 to 63 lowercase letters, digits, or hyphens, starting and ending with a letter or digit.
Last modified on September 19, 2026