Authentication | EZGH Cloud

The credentials the EZGH Cloud APIs accept, how to send them, and what each can do.

Every API call is made as a user or a bot in an organization, and is allowed only if that principal’s IAM policies allow it. See IAM.

Credentials

Credential	Looks like	Use it for
API key	`ezgh_` and 40 letters and digits	Your code, scripts and CI
CLI login	`ezgh_at_` and 43 letters and digits	The `ezgh` CLI, after `ezgh login`
Console session	A cookie set when you sign in at `login.ezghcloud.com`	The console

Send an API key in the Authorization header:

curl https://orgs.ezghcloud.com/v1/organizations \
  -H "Authorization: Bearer $EZGH_API_KEY"

A request with an Authorization header uses it and ignores any cookie.
Any other value in Authorization (a malformed key, a refresh token, another scheme) returns 401 unauthenticated. So do an unknown, expired or revoked key.
Keep keys secret. API keys and CLI tokens start with ezgh_, which you can match in secret scanning.

API keys

An API key acts as its owner, a user or a bot, with exactly the owner’s access. It has no permissions of its own. Access is checked on every request, so a key follows its owner’s policies as they change, and stops working when its owner leaves or is removed from the organization. To give code less access than you have, create a bot with narrower policies and a key for the bot.

Create a key in the console (account menu > API keys > Create API key), with ezgh iam api-keys create, or with CreateApiKey. See Make your first API call.
Expiry: 1 to 365 days, or never. The console offers 30 days, 90 days, 1 year and Never.
Shown once. Afterwards, only its first 11 characters (for example ezgh_Ab3dE6) are shown.
Revoking a key stops it at once.

An API key can’t:

create organizations or API keys;
leave an organization, or accept or decline invitations;
delete the organization or make someone else root, even the root user’s key.

CLI logins

ezgh login signs the CLI in as you, in your browser (ezgh login --device on machines without one). The CLI gets an access token that acts as you, with your access, and sends it as Authorization: Bearer ezgh_at_…. See ezgh CLI.

An access token lasts 1 hour. The CLI refreshes it with a refresh token, which lasts 30 days from its last use.
A CLI login can do what you can, including creating API keys, except delete the organization or make someone else root.
A login ends with ezgh logout, Sign out everywhere, or a password change. Signing out of the browser doesn’t end it.

Console sessions

Signing in at login.ezghcloud.com sets a session cookie that the console uses. Deleting the organization and making someone else root work only with this session, signed in as the root user.

Calling from a browser

The APIs allow cross-origin browser requests only from the EZGH Cloud console. Call them from a server, a script or the CLI.