Skip to main content
POST
Set up AWS access through an env zero environment

Authorizations

Authorization
string
header
required

env zero API authentication is done via API keys. An API Key can either be created by an organization administrator, in which case it will not be connected to any specific user, or via Personal API Keys to authenticate as a user.

Creating an API Key with a Specific Role

  • Once you've created your organization, you can set up and manage API Keys.
  • Navigate to the Organization Settings page and click the API Keys tab.
  • Click Add API Key and enter a name for your key in the Name field. This name is for reference purposes only and isn't used directly in authentication.

❗️Save Your API Key ID and secret The secret will not be available after you close this window.

Creating a Personal API Key

  • Click on your avatar (located on the top right of the screen)
  • Click on Personal Settings
  • Select the API Keys tab
  • Click Add API Key, and enter a name for your key in the Name field. This name is for reference purposes and isn't used directly in authentication.

❗️Save your API Key ID & secret The secret will not be available after you close this window.

Using an API Key to Authenticate

Authentication of the env zero API is done using the Basic Authentication method. Each request made should include the API Key ID as the username, and the API Key secret as the password. For example, when using curl, we can include these parameters via flag --user {API Key ID}:{API Key Secret}.

API Key Permissions

When creating an API key through the organization settings, you will need to choose if you’d like to grant it Organization Admin or User permissions. In case of the latter, you can assign fine-grained permissions per project. Personal API Keys can be created through the user’s profile page and will have the same permissions as the user has.

Rate Limits

env zero API allows up to 1K requests per 60 seconds, requests are aggregated by IP, HTTP Method and URI. If you exceed this limit, you will receive a 429 status code.

Body

application/json
organizationId
string
required
deploymentCredentialId
string
required

An organization-level AWS_OIDC or AWS_ASSUMED_ROLE_FOR_DEPLOYMENT credential that deploys the setup.

Required string length: 1 - 128
accountMode
enum<string>
required
Available options:
single,
organization
includeCostData
boolean

Defaults to true. False skips the CUR 2.0 export and the cost sync.

signInMethod
enum<string>

How CloudQuery signs in to the Cloud Compass read role: assume_role (the default), with the tenant sync role and an External ID, or oidc, with the tenant's web identity.

Available options:
assume_role,
oidc
deployAccountIds
string[]

Organization mode only: member accounts that get a deploy role and a deployment credential.

Maximum array length: 200
Pattern: ^\d{12}$
deployRolePolicyArns
string[]

Organization mode only: AWS managed policy ARNs of the member accounts' deploy roles. Defaults to AdministratorAccess.

Required array length: 1 - 10 elements
deployRolePermissionsBoundaryArn
string

Organization mode only: a customer managed policy ARN, whose path and name each member account must have, as the deploy roles' permissions boundary.

deployProjectIds
string[]

Organization mode only, needed with deployAccountIds unless deployTrustedPrincipalArn is given: the env zero projects whose deployments may sign in to the deploy roles. AWS refuses any other project's deployments; adding a project means a Retry with the new list.

Maximum array length: 20

An env zero project ID, as the deploy roles' trust names it.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
deployTrustedPrincipalArn
string

Organization mode only: the IAM role of the organization's self-hosted agent. The deploy roles then trust that role, with the organization ID as External ID, instead of env zero's OIDC tokens.

organizationUnitIds
string[]

Organization mode only: the OUs Cloud Compass reads, picked before the apply. Empty reads the whole Organization. With it, env zero creates the Cloud Compass credential once the apply finishes, as it does for one account; without it, the client picks the OUs then.

Maximum array length: 1000
Pattern: ^(ou-[0-9a-z]{4,32}-[a-z0-9]{8,32}|r-[0-9a-z]{4,32})$
templateRepository
string

Any public GitHub repository to deploy instead of env zero's template, such as a fork of env0/setup. It must keep the template's variables and outputs. Needs the CREATE_AND_EDIT_TEMPLATES permission, since its code runs with the deployment credential.

Pattern: ^https://github\.com/[A-Za-z0-9][A-Za-z0-9-]{0,38}/(?!\.\.?$)[A-Za-z0-9._-]{1,100}$
templateRevision
string

With templateRepository only: the branch, tag or commit to deploy. Defaults to the repository's default branch. Start resolves it to a commit, and Retries deploy that commit, except after the repository lacked the template's outputs: that Retry resolves it again, so a fix pushed to it deploys.

Maximum string length: 255
Pattern: ^(?![-/])(?!.*\.\.)[\w./-]*[\w.-]$
templatePath
string

With templateRepository only: the repository's folder that holds the template. Defaults to aws.

Maximum string length: 255
Pattern: ^(?!-)(?!.*(^|/)\.\.?(/|$))[\w.-]+(/[\w.-]+)*$
projectName
string

The name of the project env zero makes for the setup. Defaults to "env zero setup". A deployment credential's setups share one project, so a later setup with the same credential goes in that project, and a different name is refused. A name another project has is refused too.

Maximum string length: 100
Pattern: ^\S(.*\S)?$
environmentName
string

The name of the setup environment. Defaults to "env zero aws roles". A name taken in the project gets a suffix. A Start that plans in the environment of an earlier failed setup keeps that environment's name.

Maximum string length: 100
Pattern: ^\S(.*\S)?$

Response

200 - application/json
setupId
string
required

The ID of the setup environment.

organizationId
string
required
accountMode
enum<string>
required
Available options:
single,
organization
includeCostData
boolean
required
deployAccountIds
string[]
required

Organization mode: the member accounts that get a deploy role.

Pattern: ^\d{12}$
deploySignInMethod
enum<string>
required

How deployments sign in to the deploy roles. oidc: env zero's OIDC tokens of the setup's projects. assume_role: the organization's self-hosted agent role.

Available options:
oidc,
assume_role
draftId
string
required

The Cloud Compass draft the environment creates the read role for.

projectId
string
required
environmentId
string
required
deploymentLogId
string
required
status
enum<string>
required

Where the setup environment is. done: the apply finished and env zero read its outputs, so the Cloud Compass draft can be verified.

Available options:
planning,
waiting_for_approval,
applying,
done,
failed
deployCredentials
object[]
required

The deployment credentials registered from the outputs, one per member account.

deployRolePolicyArns
string[]

Organization mode: the deploy roles' managed policies, when not AdministratorAccess.

deployRolePermissionsBoundaryArn
string

Organization mode: the deploy roles' permissions boundary.

deployProjectIds
string[]

Organization mode with OIDC deploy roles: the projects whose deployments may sign in to them.

deployTrustedPrincipalArn
string

Organization mode: the self-hosted agent role the deploy roles trust instead of OIDC tokens.

templateRepository
string

The repository the setup deploys instead of env zero's template, the commit Start resolved its revision to, and its folder.

templateRevision
string
templateRef
string

The branch, tag or commit Start was given for the repository. Absent for its default branch.

templatePath
string
planSummary
object

Known once the plan ran.

failure
object
approvalsPending
boolean

waiting_for_approval only: env zero approved the plan, which still waits, so the setup project's approval policy needs more approvers. They approve it in env zero.

readRoleFailures
object[]

Organization mode, done only: the member accounts whose read role stack is not current, read from AWS with the deploying credential. Empty when env zero read them and none failed; left out when it could not read them. A done setup with any can be retried with repairReadRoles, which deploys the member read roles again.

readRoleRepair
boolean

Organization mode: the setup's current run is a Retry that deploys failed member read roles again.

readRolesRepairedAt
string

When reading the last read role repair's outputs finished.

readRolesUnchecked
enum<string>

done, Organization mode, when env zero did not read the member read roles. self_hosted_agent: the deploying role trusts a self-hosted agent, which env zero cannot stand in for, so it never reads them. no_sign_in: the deploying credential is gone or the organization turned OIDC off, so no read works until that changes. read_failed: the read failed or AWS answered too slowly; a later read may work.

Available options:
self_hosted_agent,
no_sign_in,
read_failed
cloudCompassCredentialId
string

done only, on a read: the active Cloud Compass credential created from the draft, which outlives the draft.