Authentication

ezgh sends one credential with every request: an OAuth login for people, or an API key for code and CI. Either one acts with exactly its owner’s IAM access. Each profile keeps its own credential.

Commands use, in order:

1. EZGH_API_KEY, when it’s set.
2. The active profile’s stored credential: its login, or an API key stored with ezgh auth set-api-key.

Without either, commands exit with code 3.

Log in

ezgh login

ezgh login opens your browser at the EZGH Cloud sign-in page, where you sign in and approve access for ezgh. The browser then returns to ezgh on your computer, at http://127.0.0.1 on a random port. ezgh also prints the URL it opens, and waits up to 5 minutes for you to finish.

• --no-browser prints the URL without opening a browser.
• Use --device over SSH, or on any machine without a browser.

Log in on another device

ezgh login --device

ezgh prints https://login.ezghcloud.com/device and a code. Open the URL on any device where you can sign in, enter the code, and approve. The code expires after 15 minutes.

What a login can do

A login acts as you, with your IAM access, like the console. It can also do what API keys can’t:

• Create API keys (ezgh iam api-keys create).
• See, accept and decline your own invitations (ezgh invitations), and leave your organization (ezgh orgs leave).

Deleting an organization and handing over the root user are available only in the console.

How long a login lasts

ezgh refreshes the login’s access token by itself when it expires, which is every hour. A login stays valid while you use ezgh with it at least once every 30 days, until you log out or the login is revoked.

Check which credential is used

ezgh auth status

Profile:     ci (from --profile)
Domain:      ezghcloud.com
Credential:  API key ezgh_Ab3dE6… stored in the profile
Stored in:   the macOS Keychain

ezgh auth status reads only what’s stored on your computer. ezgh whoami asks the platform who the credential acts as: the organization, the user or bot, and whether it’s the root user.

ezgh never prints a credential. It shows at most an API key’s first 11 characters.

Use an API key

Create a key while logged in, in the console or with the CLI. For CI, create a bot with only the policies it needs, and a key for the bot:

ezgh iam bots create deployer
ezgh iam policies attach ReadOnlyAccess --bot deployer
ezgh iam api-keys create ci --bot deployer --expires-in-days 90 > ci-key.txt

The key is printed once, on standard output. See API keys.

In an environment variable

Set EZGH_API_KEY. It takes precedence over the active profile’s credential:

# GitHub Actions
- run: ezgh projects list -o json
  env:
    EZGH_API_KEY: ${{ secrets.EZGH_API_KEY }}

In a profile

ezgh auth set-api-key stores a key as a profile’s credential. It reads the key from standard input, never from an argument, and checks it before storing it unless you pass --no-verify:

ezgh auth set-api-key --profile ci < ci-key.txt

On a terminal, it asks you to paste the key and doesn’t echo it. The profile is created if it doesn’t exist.

Where credentials are stored

Entries use the service name ezgh-cli and the profile’s name as the account. Where no keychain is available, such as in CI, containers or SSH sessions without a desktop session, credentials go in credentials.json in the configuration directory, readable only by you.

EZGH_CREDENTIAL_STORE chooses the store:

Log out

ezgh logout

ezgh logout revokes the active profile’s login, which ends it on every computer it was copied to, and deletes its stored tokens. If revoking fails, for example because the platform can’t be reached, the tokens are still deleted, and ezgh exits with code 1.

• --profile <name> logs out of one profile, and --all logs out of every profile.
• For a profile with a stored API key, ezgh logout only deletes the key from your computer. The key keeps working until you revoke it with ezgh iam api-keys delete.
• ezgh logout doesn’t change EZGH_API_KEY. Unset it yourself.