API keys | EZGH Cloud

Create, use and revoke API keys, which act as a user or bot with exactly its access.

An API key is a credential for code. It acts as its owner, a user or a bot, with exactly the owner’s access. A key has no permissions of its own: its access is checked on every request and changes when its owner’s does. To give code less access than you have, create a bot with only the policies it needs, and a key for the bot.

Property	Value
Format	`ezgh_` followed by 40 letters and digits
Shown	Once, when it’s created
Identified by	Its name and its first characters, like `ezgh_Ab3dE6…`
Expiry	1 to 365 days after creation, or never
Name	1 to 100 characters

Create an API key

You create keys signed in, in the console or the CLI. An API key can’t create API keys.

A key for yourself needs apiKeys.create. It’s included in BasicAccess.
A key for a bot needs bots.createApiKey on the bot. See Create an API key for a bot.
Nobody can create a key for another user.

Open the account menu and select API keys. This opens the API keys tab of your own user page.
Select Create API key.
Enter a Name and choose when it Expires: 30 days, 90 days, 1 year or Never. The default is 90 days.
Review, then select Create key.
Copy the key. It won’t be shown again.

ezgh iam api-keys create laptop --expires-in-days 90

The key is printed once, on standard output. Without --expires-in-days, the key doesn’t expire. Add --bot <bot> to create the key for a bot.

Use an API key

Send the key as a bearer token:

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

Every EZGH Cloud API accepts API keys the same way. A key that’s malformed, revoked or expired, or whose owner has left the organization, gets 401.

List API keys

Everyone can see their own keys. Seeing every key in the organization needs apiKeys.list. In the console, a user’s or bot’s keys are on the API keys tab of their page, with the date each was Last used.

ezgh iam api-keys list

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

See ListApiKeys.

Revoke an API key

A revoked key stops working immediately. Revoking can’t be undone. You can revoke your own keys; revoking anyone else’s needs apiKeys.delete.

On the API keys tab of the owner’s page, select Revoke next to the key, then confirm.

ezgh iam api-keys delete laptop

The key can be given by ID, name or prefix.

curl -X DELETE https://orgs.ezghcloud.com/v1/organizations/$ORG_ID/api-keys/$KEY_ID \
  -H "Authorization: Bearer $EZGH_API_KEY"

See DeleteApiKey.

Keys are also revoked when:

their owner is removed from the organization or leaves it;
their owner is a bot and the bot is deleted;
their owner is suspended by your identity provider over SCIM. Reactivating the user doesn’t restore the keys.