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

# env zero API access

> Authenticate to the env zero REST API with an API key, make a first request, and handle rate limits, pagination, and errors.

The env zero REST API is served from `https://api.env0.com`. The [API reference](https://docs.envzero.com/api-reference) lists every endpoint. This page covers what applies to all of them: authentication, rate limits, pagination, and errors.

To work from a terminal or CI without writing HTTP calls, use the [env zero CLI](https://docs.envzero.com/guides/community-and-resources/support-and-help/env-zero-cli.md).

## Authentication

The API uses HTTP Basic authentication. Send the API key ID as the username and the API key secret as the password on every request.

| Key | Created in | Permissions |
| :- | :- | :- |
| Admin API key | **Organization Settings** > **API Keys**, by an organization admin | Organization Admin |
| User API key | **Organization Settings** > **API Keys**, by an organization admin | The roles you assign it, like a user |
| Personal API key | **Personal settings** > **Personal API Keys**, by any user | The permissions of the user who created it |

Admin and user API keys can also be [read-only](https://docs.envzero.com/guides/admin-guide/user-role-and-team-management/api-keys.md#read-only-api-key). To create and delete keys, see [API keys](https://docs.envzero.com/guides/admin-guide/user-role-and-team-management/api-keys.md). The CLI manages them with [`env0 api-key` and `env0 personal-api-key`](https://docs.envzero.com/guides/community-and-resources/support-and-help/env-zero-cli/command-reference#api-keys).

env zero caches a successful authentication for up to 1 hour. Deleting a key, or changing its permissions, can take up to 1 hour to apply.

If your organization has an [IP allowlist](https://docs.envzero.com/guides/overview/security-overview/ip-allowlisting.md), or the key has its own [allowed IPs](https://docs.envzero.com/guides/overview/security-overview/ip-allowlisting.md#allowed-ips-for-one-api-key), API key requests from addresses outside them fail with `401`.

## Make your first request

**1. Create an API key**

Create a key as described in [API keys](https://docs.envzero.com/guides/admin-guide/user-role-and-team-management/api-keys.md). The secret is shown once, so copy the key ID and secret before you close the dialog.

**2. Export the key**

```bash theme={null}
export ENV0_API_KEY_ID="<YOUR_API_KEY_ID>"
export ENV0_API_KEY_SECRET="<YOUR_API_KEY_SECRET>"
```

The env zero CLI reads the same variables.

**3. List your organizations**

```bash theme={null}
curl -s -u "$ENV0_API_KEY_ID:$ENV0_API_KEY_SECRET" https://api.env0.com/organizations | jq '.[] | {id, name}'
```

The response lists each organization the key can access:

```json theme={null}
{
  "id": "3f2b8c1e-7d4a-4e9b-a6c5-0b1d2e3f4a5b",
  "name": "Acme"
}
```

Pass an organization `id` as the `organizationId` query parameter to endpoints such as [List Projects](https://docs.envzero.com/api-reference/projects/list-projects.md) and [List Environments](https://docs.envzero.com/api-reference/environments/list-environments.md).

## Rate limits

Requests are counted per source IP address, HTTP method, and URL path, over the last 60 seconds:

| Requests | Limit per 60 seconds |
| :- | :- |
| `GET /environments`, `POST` to any path that starts with `/environments`, and `PUT` to any path under `/environments/deployments/` | 200 |
| All other requests | 1,000 |

The URL path is counted without the query string. `POST /environments/<ENVIRONMENT_A>/deployments` and `POST /environments/<ENVIRONMENT_B>/deployments` have separate limits. `GET /environments?projectId=<PROJECT_A>` and `GET /environments?projectId=<PROJECT_B>` share one.

A request over the limit gets `429 Too Many Requests` with a plain-text body. There is no `Retry-After` header. Back off and retry. Requests succeed again once the count for the last 60 seconds drops below the limit.

## Pagination

List endpoints page in one of three ways. Each endpoint's API reference page lists the parameters it accepts. Endpoints without paging parameters, such as [List Organizations](https://docs.envzero.com/api-reference/organization/list-organizations.md), return every row in one response.

### Offset and limit

[List Environments](https://docs.envzero.com/api-reference/environments/list-environments.md) and [List Deployments](https://docs.envzero.com/api-reference/environments/list-deployments.md) take `limit` (rows per page) and `offset` (rows to skip, default `0`). List Environments returns at most 100 rows per page.

```bash theme={null}
curl -s -u "$ENV0_API_KEY_ID:$ENV0_API_KEY_SECRET" \
  "https://api.env0.com/environments?organizationId=<YOUR_ORGANIZATION_ID>&limit=100&offset=100"
```

Advance `offset` by the number of rows each page returned, and stop when a page is empty. List Deployments can return fewer rows than `limit` while more remain, to keep the response under its size limit, so a short page is not always the last one.

### Page key

[Fetch Audit Logs](https://docs.envzero.com/api-reference/audit-events/fetch-audit-logs.md) returns `events` and a `nextPageKey`. Pass `nextPageKey` as `offset` to get the next page. The last page has no `nextPageKey`. With filters, a page can have no events and still return a `nextPageKey`, so keep going until it is absent. `limit` defaults to 50, with a maximum of 1,000.

### Page number

Cloud Compass resource lists, such as [List Cloud Compass Managed Resources Of An Environment](https://docs.envzero.com/api-reference/cloud-compass/list-cloud-compass-managed-resources-of-an-environment.md), take `page` (starting at `1`) and `pageSize`, and return the `total` row count.

## Errors

Errors use standard HTTP status codes. Errors from env zero services have a plain-text body, so read it as text. A `401`, and a `403` for a path that doesn't exist, come from the API gateway instead and have a JSON body with a `message` field. A `400` body looks like this:

```text theme={null}
/body must have required property 'name', /body must have required property 'organizationId'
```

| Status | Meaning |
| :- | :- |
| `400` | Invalid input. The message names the field. |
| `401` | Missing or invalid credentials, or an address outside your organization's IP allowlist or the key's allowed IPs. The body is `{"message":"Unauthorized"}`. |
| `403` | The key is missing a permission. The message names the permissions to add. A `403` whose message mentions `Credential` and `Signature` means the path or method does not exist. Check the URL against the [API reference](https://docs.envzero.com/api-reference). |
| `404` | The resource does not exist. |
| `409` | Conflict with an existing resource, such as an API key name already in use. |
| `429` | Rate limit reached. See [Rate limits](#rate-limits). |
| `500` | Unexpected error. The message includes a request ID. |

Every response has an `x-amzn-requestid` header. Include it, or the request ID from a `500` message, when you [contact support](https://docs.envzero.com/guides/community-and-resources/support-and-help/support.md).

## Next steps

To give AI assistants and IDEs access to env zero with an API key, set up the [env zero MCP server](https://docs.envzero.com/guides/community-and-resources/support-and-help/mcp-server.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.