» Organizations API

The Organizations API is used to list, show, create, update, and destroy organizations.

» List Organizations

GET /organizations

Status Response Reason
200 JSON API document (type: "organizations") The request was successful
404 JSON API error object Organization not found or user unauthorized to perform action

» Sample Request 

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/organizations

» Sample Response 

{
  "data": [
    {
      "id": "hashicorp",
      "type": "organizations",
      "attributes": {
        "name": "hashicorp",
        "cost-estimation-enabled": true,
        "created-at": "2017-09-07T14:34:40.492Z",
        "email": "user@example.com",
        "session-timeout": null,
        "session-remember": null,
        "collaborator-auth-policy": "password",
        "plan-expired": false,
        "plan-expires-at": null,
        "plan-is-trial": false,
        "plan-is-enterprise": false,
        "permissions": {
          "can-update": true,
          "can-destroy": true,
          "can-access-via-teams": true,
          "can-create-module": true,
          "can-create-team": true,
          "can-create-workspace": true,
          "can-manage-users": true,
          "can-manage-subscription": true,
          "can-manage-sso": false,
          "can-update-oauth": true,
          "can-update-sentinel": true,
          "can-update-ssh-keys": true,
          "can-update-api-token": true,
          "can-traverse": true,
          "can-start-trial": false,
          "can-update-agent-pools": false
        },
        "fair-run-queuing-enabled": true,
        "saml-enabled": false,
        "owners-team-saml-role-id": null,
        "two-factor-conformant": true
      },
      "relationships": {
        "oauth-tokens": {
          "links": {
            "related": "/api/v2/organizations/hashicorp/oauth-tokens"
          }
        },
        "authentication-token": {
          "links": {
            "related": "/api/v2/organizations/hashicorp/authentication-token"
          }
        },
        "entitlement-set": {
          "data": {
            "id": "org-MxtxBC6ihhU6u8AG",
            "type": "entitlement-sets"
          },
          "links": {
            "related": "/api/v2/organizations/hashicorp/entitlement-set"
          }
        },
        "subscription": {
          "links": {
            "related": "/api/v2/organizations/hashicorp/subscription"
          }
        }
      },
      "links": {
        "self": "/api/v2/organizations/hashicorp"
      }
    }
  ]
}

» Show an Organization

GET /organizations/:organization_name

Parameter Description
:organization_name The name of the organization to show
Status Response Reason
200 JSON API document (type: "organizations") The request was successful
404 JSON API error object Organization not found or user unauthorized to perform action

» Sample Request 

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/organizations/hashicorp

» Sample Response 

{
  "id": "hashicorp",
  "type": "organizations",
  "attributes": {
    "name": "hashicorp",
    "cost-estimation-enabled": true,
    "created-at": "2017-09-07T14:34:40.492Z",
    "email": "user@example.com",
    "session-timeout": null,
    "session-remember": null,
    "collaborator-auth-policy": "password",
    "plan-expired": false,
    "plan-expires-at": null,
    "plan-is-trial": false,
    "plan-is-enterprise": false,
    "permissions": {
      "can-update": true,
      "can-destroy": true,
      "can-access-via-teams": true,
      "can-create-module": true,
      "can-create-team": true,
      "can-create-workspace": true,
      "can-manage-users": true,
      "can-manage-subscription": true,
      "can-manage-sso": false,
      "can-update-oauth": true,
      "can-update-sentinel": true,
      "can-update-ssh-keys": true,
      "can-update-api-token": true,
      "can-traverse": true,
      "can-start-trial": false,
      "can-update-agent-pools": false
    },
    "fair-run-queuing-enabled": true,
    "saml-enabled": false,
    "owners-team-saml-role-id": null,
    "two-factor-conformant": true
  },
  "relationships": {
    "oauth-tokens": {
      "links": {
        "related": "/api/v2/organizations/hashicorp/oauth-tokens"
      }
    },
    "authentication-token": {
      "links": {
        "related": "/api/v2/organizations/hashicorp/authentication-token"
      }
    },
    "entitlement-set": {
      "data": {
        "id": "org-MxtxBC6ihhU6u8AG",
        "type": "entitlement-sets"
      },
      "links": {
        "related": "/api/v2/organizations/hashicorp/entitlement-set"
      }
    },
    "subscription": {
      "links": {
        "related": "/api/v2/organizations/hashicorp/subscription"
      }
    }
  },
  "links": {
    "self": "/api/v2/organizations/hashicorp"
  }
}

» Create an Organization

POST /organizations

Status Response Reason
201 JSON API document (type: "organizations") The organization was successfully created
404 JSON API error object Organization not found or user unauthorized to perform action
422 JSON API error object Malformed request body (missing attributes, wrong types, etc.)

» Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key path Type Default Description
data.type string Must be "organizations"
data.attributes.name string Name of the organization
data.attributes.email string Admin email address
data.attributes.session-timeout integer 20160 Session timeout after inactivity (minutes)
data.attributes.session-remember integer 20160 Session expiration (minutes)
data.attributes.collaborator-auth-policy string password Authentication policy (password or two_factor_mandatory)
data.attributes.cost-estimation-enabled boolean true Whether or not the cost estimation feature is enabled for all workspaces in the organization. Defaults to true. In a Terraform Cloud organization which does not have Teams & Governance features, this value is always false and cannot be changed. In Terraform Enterprise, Cost Estimation must also be enabled in Site Administration.
data.attributes.owners-team-saml-role-id string (nothing) Optional. SAML only The name of the "owners" team

» Sample Payload 

{
  "data": {
    "type": "organizations",
    "attributes": {
      "name": "hashicorp",
      "email": "user@example.com"
    }
  }
}

» Sample Request 

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations

» Sample Response 

{
  "id": "hashicorp",
  "type": "organizations",
  "attributes": {
    "name": "hashicorp",
    "cost-estimation-enabled": true,
    "created-at": "2017-09-07T14:34:40.492Z",
    "email": "user@example.com",
    "session-timeout": null,
    "session-remember": null,
    "collaborator-auth-policy": "password",
    "plan-expired": false,
    "plan-expires-at": null,
    "plan-is-trial": false,
    "plan-is-enterprise": false,
    "permissions": {
      "can-update": true,
      "can-destroy": true,
      "can-access-via-teams": true,
      "can-create-module": true,
      "can-create-team": true,
      "can-create-workspace": true,
      "can-manage-users": true,
      "can-manage-subscription": true,
      "can-manage-sso": false,
      "can-update-oauth": true,
      "can-update-sentinel": true,
      "can-update-ssh-keys": true,
      "can-update-api-token": true,
      "can-traverse": true,
      "can-start-trial": false,
      "can-update-agent-pools": false
    },
    "fair-run-queuing-enabled": true,
    "saml-enabled": false,
    "owners-team-saml-role-id": null,
    "two-factor-conformant": true
  },
  "relationships": {
    "oauth-tokens": {
      "links": {
        "related": "/api/v2/organizations/hashicorp/oauth-tokens"
      }
    },
    "authentication-token": {
      "links": {
        "related": "/api/v2/organizations/hashicorp/authentication-token"
      }
    },
    "entitlement-set": {
      "data": {
        "id": "org-MxtxBC6ihhU6u8AG",
        "type": "entitlement-sets"
      },
      "links": {
        "related": "/api/v2/organizations/hashicorp/entitlement-set"
      }
    },
    "subscription": {
      "links": {
        "related": "/api/v2/organizations/hashicorp/subscription"
      }
    }
  },
  "links": {
    "self": "/api/v2/organizations/hashicorp"
  }
}

» Update an Organization

PATCH /organizations/:organization_name

Parameter Description
:organization_name The name of the organization to update
Status Response Reason
200 JSON API document (type: "organizations") The organization was successfully updated
404 JSON API error object Organization not found or user unauthorized to perform action
422 JSON API error object Malformed request body (missing attributes, wrong types, etc.)

» Request Body

This PATCH endpoint requires a JSON object with the following properties as a request payload.

Key path Type Default Description
data.type string Must be "organizations"
data.attributes.name string Name of the organization
data.attributes.email string Admin email address
data.attributes.session-timeout integer 20160 Session timeout after inactivity (minutes)
data.attributes.session-remember integer 20160 Session expiration (minutes)
data.attributes.collaborator-auth-policy string password Authentication policy (password or two_factor_mandatory)
data.attributes.cost-estimation-enabled boolean true Whether or not the cost estimation feature is enabled for all workspaces in the organization. Defaults to true. In a Terraform Cloud organization which does not have Teams & Governance features, this value is always false and cannot be changed. In Terraform Enterprise, Cost Estimation must also be enabled in Site Administration.
data.attributes.owners-team-saml-role-id string (nothing) Optional. SAML only The name of the "owners" team

» Sample Payload 

{
  "data": {
    "type": "organizations",
    "attributes": {
      "email": "admin@example.com"
    }
  }
}

» Sample Request 

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations/hashicorp

» Sample Response 

{
  "id": "hashicorp",
  "type": "organizations",
  "attributes": {
    "name": "hashicorp",
    "cost-estimation-enabled": true,
    "created-at": "2017-09-07T14:34:40.492Z",
    "email": "admin@example.com",
    "session-timeout": null,
    "session-remember": null,
    "collaborator-auth-policy": "password",
    "plan-expired": false,
    "plan-expires-at": null,
    "plan-is-trial": false,
    "plan-is-enterprise": false,
    "permissions": {
      "can-update": true,
      "can-destroy": true,
      "can-access-via-teams": true,
      "can-create-module": true,
      "can-create-team": true,
      "can-create-workspace": true,
      "can-manage-users": true,
      "can-manage-subscription": true,
      "can-manage-sso": false,
      "can-update-oauth": true,
      "can-update-sentinel": true,
      "can-update-ssh-keys": true,
      "can-update-api-token": true,
      "can-traverse": true,
      "can-start-trial": false,
      "can-update-agent-pools": false
    },
    "fair-run-queuing-enabled": true,
    "saml-enabled": false,
    "owners-team-saml-role-id": null,
    "two-factor-conformant": true
  },
  "relationships": {
    "oauth-tokens": {
      "links": {
        "related": "/api/v2/organizations/hashicorp/oauth-tokens"
      }
    },
    "authentication-token": {
      "links": {
        "related": "/api/v2/organizations/hashicorp/authentication-token"
      }
    },
    "entitlement-set": {
      "data": {
        "id": "org-MxtxBC6ihhU6u8AG",
        "type": "entitlement-sets"
      },
      "links": {
        "related": "/api/v2/organizations/hashicorp/entitlement-set"
      }
    },
    "subscription": {
      "links": {
        "related": "/api/v2/organizations/hashicorp/subscription"
      }
    }
  },
  "links": {
    "self": "/api/v2/organizations/hashicorp"
  }
}

» Destroy an Organization

DELETE /organizations/:organization_name

Parameter Description
:organization_name The name of the organization to destroy
Status Response Reason
204 The organization was successfully destroyed
404 JSON API error object Organization not found or user unauthorized to perform action

» Sample Request 

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/organizations/hashicorp

» Sample Response

The response body will be empty if successful.

» Show the Entitlement Set

This endpoint shows the entitlements for an organization.

GET /organizations/:organization_name/entitlement-set

Parameter Description
:organization_name The name of the organization's entitlement set to view
Status Response Reason
200 JSON API document (type: "entitlement-sets") The request was successful
404 JSON API error object Organization not found or user unauthorized to perform action

» Sample Request 

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/organizations/hashicorp/entitlement-set

» Sample Response 

{
  "data": {
    "id": "hashicorp",
    "type": "entitlement-sets",
    "attributes": {
      "cost-estimation": true,
      "configuration-designer": true,
      "operations": true,
      "private-module-registry": true,
      "sentinel": true,
      "state-storage": true,
      "teams": true,
      "vcs-integrations": true,
      "usage-reporting": false,
      "user-limit": null,
      "self-serve-billing": true,
      "audit-logging": false,
      "agents": false,
      "sso": false
    },
    "links":{
      "self": "api/v2/entitlement-sets/hashicorp"
    }
  }
}