> ## 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](/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](/guides/community-and-resources/support-and-help/env-zero-cli).

## 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](/guides/admin-guide/user-role-and-team-management/api-keys#read-only-api-key). To create and delete keys, see [API keys](/guides/admin-guide/user-role-and-team-management/api-keys). The CLI manages them with [`env0 api-key` and `env0 personal-api-key`](/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](/guides/overview/security-overview/ip-allowlisting), API key requests from addresses outside it fail with `401`.

## Make your first request

<Steps>
  <Step title="Create an API key">
    Create a key as described in [API keys](/guides/admin-guide/user-role-and-team-management/api-keys). The secret is shown once, so copy the key ID and secret before you close the dialog.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](/api-reference/projects/list-projects) and [List Environments](/api-reference/environments/list-environments).
  </Step>
</Steps>

## 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](/api-reference/organization/list-organizations), return every row in one response.

### Offset and limit

[List Environments](/api-reference/environments/list-environments) and [List Deployments](/api-reference/environments/list-deployments) 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](/api-reference/audit-events/fetch-audit-logs) 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](/api-reference/cloud-compass/list-cloud-compass-managed-resources-of-an-environment), 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. 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](/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](/guides/community-and-resources/support-and-help/support).


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