---
title: "Authentication"
description: "The credentials the EZGH Cloud APIs accept, how to send them, and what each can do."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

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](/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:

```sh
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](/orgs-api/apiKeys/CreateApiKey/). See
  [Make your first API call](/get-started/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](/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.

Source: https://docs.ezghcloud.com/api/authentication/index.mdx