Skip to Content

CLI authentication

The CLI authenticates with an admin API key. A subscription login is imported separately; it is not the credential used to administer Modem.

Browser login

modem-cli auth login --web modem-cli auth login -p read,customers:write --sandbox

Without flags, an interactive terminal offers browser approval or a pasted key. Browser approval initially requests full access, All projects, both modes and a 90-day lifetime. -p, --project, --sandbox, --live, --expires and the approval page’s Customize control change that grant. See permissions.

The CLI opens the selected app’s authorization page and waits up to five minutes on a dynamically allocated 127.0.0.1 callback port. It validates callback path, method, host and state, then exchanges a single-use code with PKCE. The browser must reach the machine running the CLI; opening the page on another machine does not forward the callback automatically.

--no-open prints the approval URL without launching a browser. --timeout-seconds changes the wait. Ctrl-C or SIGTERM cancels before a valid callback is accepted. After code exchange starts, the CLI finishes receiving and saving a possibly issued replacement rather than abandoning its secret. If approval reports app access pending, obtain access before starting a fresh login.

Existing key and remote shells

modem-cli auth login --with-token < /path/to/private-key.txt

In a terminal this uses a masked prompt; when piped it reads stdin. The key is verified against the selected target before storage. There is no key-value command-line flag. Browser-only grant options cannot be combined with --with-token: a pasted key keeps its existing grant.

A CI process can supply PRETERNATURAL_MODEM_ADMIN_API_KEY without saving a login; see automation.

Inspect and change access

modem-cli auth status modem-cli auth status --json modem-cli api-keys permissions modem-cli auth refresh -p customers:write modem-cli auth refresh -r full -p read

auth status verifies stored keys against their own deployments. It shows identity, access and expiry. auth refresh starts from the stored grant and obtains browser approval for a replacement. With no flags, it renews expiry for the original lifetime. It can add/remove permissions, add selected projects or select All projects, and change modes.

auth token prints the selected key; auth status --show-token also reveals secrets. Use these only when deliberately passing a secret to another trusted process. Ordinary status output omits them.

Rotate and log out

modem-cli auth rotate --grace 1h modem-cli auth logout

Rotation changes the secret while preserving identity, name, permissions and expiry. Grace can be now, 1h, 24h or 7d. Use browser refresh when you need a new grant or expiry.

A key created through CLI browser approval is owned by that CLI login. A subsequent browser login or refresh replaces it, and logout normally revokes it. A pasted key may be used elsewhere, so logout only forgets it. --keep-key forgets a browser-issued key without revocation.

Failed revocation retains the stored login unless you explicitly choose to keep the remote key. auth logout --all removes all target logins; it can also remove an unreadable old config so auth login can start over. Keep a record of credentials that still need separate revocation.

For another script or service, api-keys create --name ci -p products:write --live asks for browser approval and prints the new secret once without saving it as the CLI login. api-keys list, get and revoke manage workspace keys according to their permissions.

Last updated on