Terraform Home

»Terraform Enterprise Settings API

Terraform Enterprise Only: The admin API is exclusive to Terraform Enterprise, and can only be used by the admins and operators who install and maintain their organization's Terraform Enterprise instance.

»List General Settings

GET /api/v2/admin/general-settings

StatusResponseReason
200JSON API document (type: "general-settings")Successfully listed General settings
404JSON API error objectUser 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/admin/general-settings

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

»Sample Response

{
  "data": {
    "id": "general",
    "type": "general-settings",
    "attributes": {
      "limit-user-organization-creation": true,
      "api-rate-limiting-enabled": true,
      "api-rate-limit": 30,
      "send-passing-statuses-for-untriggered-speculative-plans": false,
      "allow-speculative-plans-on-pull-requests-from-forks": false,
      "default-remote-state-access": true
    }
  }
}

{
  "data": {
    "id": "general",
    "type": "general-settings",
    "attributes": {
      "limit-user-organization-creation": true,
      "api-rate-limiting-enabled": true,
      "api-rate-limit": 30,
      "send-passing-statuses-for-untriggered-speculative-plans": false,
      "allow-speculative-plans-on-pull-requests-from-forks": false,
      "default-remote-state-access": true
    }
  }
}

»Update General Settings

PATCH /api/v2/admin/general-settings

StatusResponseReason
200JSON API document (type: "general-settings")Successfully updated the General settings
404JSON API error objectUser unauthorized to perform action
422JSON API error objectMalformed 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 pathTypeDefaultDescription
data.attributes.allow-speculative-plans-on-pull-requests-from-forksboolfalseWhen set to false, speculative plans are not run on pull requests from forks of a repository. It is currently supported for the following VCS providers: GitHub.com, GitHub.com (OAuth), GitHub Enterprise, Bitbucket Cloud, Azure DevOps Server, Azure DevOps Services. To learn more about this setting, refer to the documentation
data.attributes.api-rate-limitinteger30The number of allowable API requests per second for any client. This value cannot be less than 30. To learn more about API Rate Limiting, refer to the rate limiting documentation
data.attributes.api-rate-limiting-enabledbooltrueWhether or not rate limiting is enabled for API requests. To learn more about API Rate Limiting, refer to the rate limiting documentation
data.attributes.default-remote-state-accessbooltrueDetermines the default value for the global-remote-state attribute on new workspaces. For more details, refer to Administration: General Settings and Workspaces API: Create a Workspace.
data.attributes.limit-user-organization-creationbooltrueWhen set to true, limits the ability to create organizations to users with the site-admin permission only.
data.attributes.send-passing-statuses-for-untriggered-speculative-plansboolfalseWhen set to true, workspaces automatically send passing commit statuses for any pull requests that don't affect their tracked files.

»Sample Payload

{
  "data": {
    "attributes": {
      "limit-user-organization-creation": true,
      "api-rate-limiting-enabled": true,
      "api-rate-limit": 50
    }
  }
}

{
  "data": {
    "attributes": {
      "limit-user-organization-creation": true,
      "api-rate-limiting-enabled": true,
      "api-rate-limit": 50
    }
  }
}

»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/admin/general-settings

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

»Sample Response

{
  "data": {
    "id": "general",
    "type": "general-settings",
    "attributes": {
      "limit-user-organization-creation": true,
      "api-rate-limiting-enabled": true,
      "api-rate-limit": 50,
      "send-passing-statuses-for-untriggered-speculative-plans": false,
      "allow-speculative-plans-on-pull-requests-from-forks": false,
      "default-remote-state-access": true
    }
  }
}

{
  "data": {
    "id": "general",
    "type": "general-settings",
    "attributes": {
      "limit-user-organization-creation": true,
      "api-rate-limiting-enabled": true,
      "api-rate-limit": 50,
      "send-passing-statuses-for-untriggered-speculative-plans": false,
      "allow-speculative-plans-on-pull-requests-from-forks": false,
      "default-remote-state-access": true
    }
  }
}

»List Cost Estimation Settings

GET /api/v2/admin/cost-estimation-settings

StatusResponseReason
200JSON API document (type: "cost-estimation-settings")Successfully listed Cost Estimation settings
404JSON API error objectUser 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/admin/cost-estimation-settings

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

»Sample Response

{
  "data": {
    "id": "cost-estimation",
    "type": "cost-estimation-settings",
    "attributes": {
      "enabled": true,
      "aws-access-key-id": "AKIAIOSFODNN7EXAMPLE",
      "aws-secret-key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "gcp-credentials": "{\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n....=\\n-----END PRIVATE KEY-----\",\"private_key_id\":\"some_id\",...}",
      "azure-client-id": "9b516fe8-415s-9119-bab0-EXAMPLEID1",
      "azure-client-secret": "9b516fe8-415s-9119-bab0-EXAMPLESEC1",
      "azure-subscription-id": "9b516fe8-415s-9119-bab0-EXAMPLEID2",
      "azure-tenant-id": "9b516fe8-415s-9119-bab0-EXAMPLEID3",
    }
  }
}

{
  "data": {
    "id": "cost-estimation",
    "type": "cost-estimation-settings",
    "attributes": {
      "enabled": true,
      "aws-access-key-id": "AKIAIOSFODNN7EXAMPLE",
      "aws-secret-key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "gcp-credentials": "{\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n....=\\n-----END PRIVATE KEY-----\",\"private_key_id\":\"some_id\",...}",
      "azure-client-id": "9b516fe8-415s-9119-bab0-EXAMPLEID1",
      "azure-client-secret": "9b516fe8-415s-9119-bab0-EXAMPLESEC1",
      "azure-subscription-id": "9b516fe8-415s-9119-bab0-EXAMPLEID2",
      "azure-tenant-id": "9b516fe8-415s-9119-bab0-EXAMPLEID3",
    }
  }
}

»Update Cost Estimation Settings

PATCH /api/v2/admin/cost-estimation-settings

StatusResponseReason
200JSON API document (type: "cost-estimation-settings")Successfully updated Cost Estimation settings
404JSON API error objectUser unauthorized to perform action
422JSON API error objectMalformed request body (missing attributes, wrong types, etc.)

»Request Body

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

If data.attributes.enabled is set to true, there must be at least one set of credentials populated with valid values. For example, either both aws-access-key-id and aws-secret-key must be set, or gcp-credentials must be set.

See SAML Configuration for more details on attribute values.

Key pathTypeDefaultDescription
data.attributes.enabledboolfalseAllows organizations to opt-in to the Cost Estimation feature.
data.attributes.aws-access-key-idstringAn AWS Access Key ID that the Cost Estimation feature will use to authorize to AWS's Pricing API.
data.attributes.aws-secret-keystringAn AWS Secret Key that the Cost Estimation feature will use to authorize to AWS's Pricing API.
data.attributes.gcp-credentialsstringA JSON string containing GCP credentials that the Cost Estimation feature will use to authorize to the Google Cloud Platform's Pricing API. This must be the contents of a valid JSON key that is downloaded when creating a Service Account in GCP.
data.attributes.azure-client-idstringAn Azure Client ID that the Cost Estimation feature will use to authorize to Azure's RateCard API.
data.attributes.azure-client-secretstringAn Azure Client Secret that the Cost Estimation feature will use to authorize to Azure's RateCard API.
data.attributes.azure-subscription-idstringAn Azure Subscription ID that the Cost Estimation feature will use to authorize to Azure's RateCard API.
data.attributes.azure-tenant-idstringAn Azure Tenant ID that the Cost Estimation feature will use to authorize to Azure's RateCard API.
{
  "data": {
    "attributes": {
      "enabled": true,
      "aws-access-key-id": "AKIAIOSFODNN7EXAMPLE",
      "aws-secret-key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "gcp-credentials": "{\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n....=\\n-----END PRIVATE KEY-----\",\"private_key_id\":\"some_id\",...}",
      "azure-client-id": "9b516fe8-415s-9119-bab0-EXAMPLEID1",
      "azure-client-secret": "9b516fe8-415s-9119-bab0-EXAMPLESEC1",
      "azure-subscription-id": "9b516fe8-415s-9119-bab0-EXAMPLEID2",
      "azure-tenant-id": "9b516fe8-415s-9119-bab0-EXAMPLEID3",
    }
  }
}

{
  "data": {
    "attributes": {
      "enabled": true,
      "aws-access-key-id": "AKIAIOSFODNN7EXAMPLE",
      "aws-secret-key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "gcp-credentials": "{\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n....=\\n-----END PRIVATE KEY-----\",\"private_key_id\":\"some_id\",...}",
      "azure-client-id": "9b516fe8-415s-9119-bab0-EXAMPLEID1",
      "azure-client-secret": "9b516fe8-415s-9119-bab0-EXAMPLESEC1",
      "azure-subscription-id": "9b516fe8-415s-9119-bab0-EXAMPLEID2",
      "azure-tenant-id": "9b516fe8-415s-9119-bab0-EXAMPLEID3",
    }
  }
}

»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/admin/cost-estimation-settings

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

»Sample Response

{
  "data": {
    "id":"cost-estimation",
    "type":"cost-estimation-settings",
    "attributes": {
      "enabled": true,
      "aws-access-key-id": "AKIAIOSFODNN7EXAMPLE",
      "aws-secret-key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "gcp-credentials": "{\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n....=\\n-----END PRIVATE KEY-----\",\"private_key_id\":\"some_id\",...}",
      "azure-client-id": "9b516fe8-415s-9119-bab0-EXAMPLEID1",
      "azure-client-secret": "9b516fe8-415s-9119-bab0-EXAMPLESEC1",
      "azure-subscription-id": "9b516fe8-415s-9119-bab0-EXAMPLEID2",
      "azure-tenant-id": "9b516fe8-415s-9119-bab0-EXAMPLEID3",
    }
  }
}

{
  "data": {
    "id":"cost-estimation",
    "type":"cost-estimation-settings",
    "attributes": {
      "enabled": true,
      "aws-access-key-id": "AKIAIOSFODNN7EXAMPLE",
      "aws-secret-key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "gcp-credentials": "{\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n....=\\n-----END PRIVATE KEY-----\",\"private_key_id\":\"some_id\",...}",
      "azure-client-id": "9b516fe8-415s-9119-bab0-EXAMPLEID1",
      "azure-client-secret": "9b516fe8-415s-9119-bab0-EXAMPLESEC1",
      "azure-subscription-id": "9b516fe8-415s-9119-bab0-EXAMPLEID2",
      "azure-tenant-id": "9b516fe8-415s-9119-bab0-EXAMPLEID3",
    }
  }
}

»List SAML Settings

GET /api/v2/admin/saml-settings

StatusResponseReason
200JSON API document (type: "saml-settings")Successfully listed SAML settings
404JSON API error objectUser 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/admin/saml-settings

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

»Sample Response

{
  "data": {
    "id": "saml",
    "type": "saml-settings",
    "attributes": {
      "enabled": true,
      "debug": false,
      "old-idp-cert": null,
      "idp-cert": "SAMPLE-CERTIFICATE",
      "slo-endpoint-url": "https://example.com/slo",
      "sso-endpoint-url": "https://example.com/sso",
      "attr-username": "Username",
      "attr-groups": "MemberOf",
      "attr-site-admin": "SiteAdmin",
      "site-admin-role": "site-admins",
      "sso-api-token-session-timeout": 1209600,
      "acs-consumer-url": "https://example.com/users/saml/auth",
      "metadata-url": "https://example.com/users/saml/metadata"
    }
  }
}

{
  "data": {
    "id": "saml",
    "type": "saml-settings",
    "attributes": {
      "enabled": true,
      "debug": false,
      "old-idp-cert": null,
      "idp-cert": "SAMPLE-CERTIFICATE",
      "slo-endpoint-url": "https://example.com/slo",
      "sso-endpoint-url": "https://example.com/sso",
      "attr-username": "Username",
      "attr-groups": "MemberOf",
      "attr-site-admin": "SiteAdmin",
      "site-admin-role": "site-admins",
      "sso-api-token-session-timeout": 1209600,
      "acs-consumer-url": "https://example.com/users/saml/auth",
      "metadata-url": "https://example.com/users/saml/metadata"
    }
  }
}

»Update SAML Settings

PATCH /api/v2/admin/saml-settings

StatusResponseReason
200JSON API document (type: "saml-settings")Successfully updated SAML settings
404JSON API error objectUser unauthorized to perform action
422JSON API error objectMalformed request body (missing attributes, wrong types, etc.)

»Request Body

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

If data.attributes.enabled is set to true, all remaining attributes must have valid values. You can omit attributes if they have a default value, or if a value was set by a previous update. Omitted attributes keep their previous values.

See SAML Configuration for more details on attribute values.

Key pathTypeDefaultDescription
data.attributes.enabledboolfalseAllows SAML to be used. If true, all remaining attributes must have valid values.
data.attributes.debugboolfalseEnables a SAML debug dialog that allows an admin to see the SAMLResponse XML and processed values during login.
data.attributes.idp-certstringIdentity Provider Certificate specifies the PEM encoded X.509 Certificate as provided by the IdP configuration.
data.attributes.slo-endpoint-urlstringSingle Log Out URL specifies the HTTPS endpoint on your IdP for single logout requests. This value is provided by the IdP configuration.
data.attributes.sso-endpoint-urlstringSingle Sign On URL specifies the HTTPS endpoint on your IdP for single sign-on requests. This value is provided by the IdP configuration.
data.attributes.attr-usernamestring"Username"Username Attribute Name specifies the name of the SAML attribute that determines the user's username.
data.attributes.attr-groupsstring"MemberOf"Team Attribute Name specifies the name of the SAML attribute that determines team membership.
data.attributes.attr-site-adminstring"SiteAdmin"Specifies the role for site admin access. Overrides the "Site Admin Role" method.
data.attributes.site-admin-rolestring"site-admins"Specifies the role for site admin access, provided in the list of roles sent in the Team Attribute Name attribute.
data.attributes.sso-api-token-session-timeoutinteger1209600Specifies the Single Sign On session timeout in seconds. Defaults to 14 days.
{
  "data": {
    "attributes": {
      "enabled": true,
      "debug": false,
      "idp-cert": "NEW-CERTIFICATE",
      "slo-endpoint-url": "https://example.com/slo",
      "sso-endpoint-url": "https://example.com/sso",
      "attr-username": "Username",
      "attr-groups": "MemberOf",
      "attr-site-admin": "SiteAdmin",
      "site-admin-role": "site-admins",
      "sso-api-token-session-timeout": 1209600
    }
  }
}

{
  "data": {
    "attributes": {
      "enabled": true,
      "debug": false,
      "idp-cert": "NEW-CERTIFICATE",
      "slo-endpoint-url": "https://example.com/slo",
      "sso-endpoint-url": "https://example.com/sso",
      "attr-username": "Username",
      "attr-groups": "MemberOf",
      "attr-site-admin": "SiteAdmin",
      "site-admin-role": "site-admins",
      "sso-api-token-session-timeout": 1209600
    }
  }
}

»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/admin/saml-settings

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

»Sample Response

{
  "data": {
    "id":"saml",
    "type":"saml-settings",
    "attributes": {
      "enabled": true,
      "debug": false,
      "old-idp-cert": "SAMPLE-CERTIFICATE",
      "idp-cert": "NEW-CERTIFICATE",
      "slo-endpoint-url": "https://example.com/slo",
      "sso-endpoint-url": "https://example.com/sso",
      "attr-username": "Username",
      "attr-groups": "MemberOf",
      "attr-site-admin": "SiteAdmin",
      "site-admin-role": "site-admins",
      "sso-api-token-session-timeout": 1209600,
      "acs-consumer-url": "https://example.com/users/saml/auth",
      "metadata-url": "https://example.com/users/saml/metadata"
    }
  }
}

{
  "data": {
    "id":"saml",
    "type":"saml-settings",
    "attributes": {
      "enabled": true,
      "debug": false,
      "old-idp-cert": "SAMPLE-CERTIFICATE",
      "idp-cert": "NEW-CERTIFICATE",
      "slo-endpoint-url": "https://example.com/slo",
      "sso-endpoint-url": "https://example.com/sso",
      "attr-username": "Username",
      "attr-groups": "MemberOf",
      "attr-site-admin": "SiteAdmin",
      "site-admin-role": "site-admins",
      "sso-api-token-session-timeout": 1209600,
      "acs-consumer-url": "https://example.com/users/saml/auth",
      "metadata-url": "https://example.com/users/saml/metadata"
    }
  }
}

»Revoke previous SAML IdP Certificate

POST /api/v2/admin/saml-settings/actions/revoke-old-certificate

When reconfiguring the IdP certificate, Terraform Enterprise will retain the old IdP certificate to allow for a rotation period. This PUT endpoint will revoke the older IdP certificate when the new IdP certificate is known to be functioning correctly.

See SAML Configuration for more details.

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://app.terraform.io/api/v2/admin/saml-settings/actions/revoke-old-certificate

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://app.terraform.io/api/v2/admin/saml-settings/actions/revoke-old-certificate

»Sample Response

{
  "data": {
    "id":"saml",
    "type":"saml-settings",
    "attributes": {
      "enabled": true,
      "debug": false,
      "old-idp-cert": null,
      "idp-cert": "NEW-CERTIFICATE",
      "slo-endpoint-url": "https://example.com/slo",
      "sso-endpoint-url": "https://example.com/sso",
      "attr-username": "Username",
      "attr-groups": "MemberOf",
      "attr-site-admin": "SiteAdmin",
      "site-admin-role": "site-admins",
      "sso-api-token-session-timeout": 1209600,
      "acs-consumer-url": "https://example.com/users/saml/auth",
      "metadata-url": "https://example.com/users/saml/metadata"
    }
  }
}

{
  "data": {
    "id":"saml",
    "type":"saml-settings",
    "attributes": {
      "enabled": true,
      "debug": false,
      "old-idp-cert": null,
      "idp-cert": "NEW-CERTIFICATE",
      "slo-endpoint-url": "https://example.com/slo",
      "sso-endpoint-url": "https://example.com/sso",
      "attr-username": "Username",
      "attr-groups": "MemberOf",
      "attr-site-admin": "SiteAdmin",
      "site-admin-role": "site-admins",
      "sso-api-token-session-timeout": 1209600,
      "acs-consumer-url": "https://example.com/users/saml/auth",
      "metadata-url": "https://example.com/users/saml/metadata"
    }
  }
}

»List SMTP Settings

GET /api/v2/admin/smtp-settings

StatusResponseReason
200JSON API document (type: "smtp-settings")Successfully listed SMTP settings
404JSON API error objectUser 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/admin/smtp-settings

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

»Sample Response

{
  "data": {
    "id": "smtp",
    "type": "smtp-settings",
    "attributes": {
      "enabled": true,
      "host": "example.com",
      "port": 25,
      "sender": "sample_user@example.com",
      "auth": "login",
      "username": "sample_user"
    }
  }
}

{
  "data": {
    "id": "smtp",
    "type": "smtp-settings",
    "attributes": {
      "enabled": true,
      "host": "example.com",
      "port": 25,
      "sender": "sample_user@example.com",
      "auth": "login",
      "username": "sample_user"
    }
  }
}

»Update SMTP Settings

PATCH /api/v2/admin/smtp-settings

When a request to this endpoint is submitted, a test message will be sent to the specified test-email-address. If the test message delivery fails, the API will return an error code indicating the reason for the failure.

StatusResponseReason
200JSON API document (type: "smtp-settings")Successfully updated the SMTP settings
401JSON API error objectSMTP user credentials are invalid
404JSON API error objectUser unauthorized to perform action
422JSON API error objectMalformed request body (missing attributes, wrong types, etc.)
500JSON API error objectSMTP server returned a server error
504JSON API error objectSMTP server timed out

»Request Body

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

If data.attributes.enabled is set to true, all remaining attributes must have valid values. You can omit attributes if they have a default value, or if a value was set by a previous update. Omitted attributes keep their previous values.

Key pathTypeDefaultDescription
data.attributes.enabledboolfalseAllows SMTP to be used. If true, all remaining attributes must have valid values.
data.attributes.hoststringThe host address of the SMTP server.
data.attributes.portintegerThe port of the SMTP server.
data.attributes.senderstringThe desired sender address.
data.attributes.authstring"none"The authentication type. Valid values are "none", "plain", and "login".
data.attributes.usernamestringThe username used to authenticate to the SMTP server. Only required if data.attributes.auth is set to "login" or "plain".
data.attributes.passwordstringThe username used to authenticate to the SMTP server. Only required if data.attributes.auth is set to "login" or "plain".
data.attributes.test-email-addressstringThe email address to send a test message to. Not persisted and only used during testing.

»Sample Payload

{
  "data": {
    "attributes": {
      "enabled": true,
      "host": "example.com",
      "port": 25,
      "sender": "sample_user@example.com",
      "auth": "login",
      "username": "sample_user",
      "password": "sample_password",
      "test-email-address": "test@example.com"
    }
  }
}

{
  "data": {
    "attributes": {
      "enabled": true,
      "host": "example.com",
      "port": 25,
      "sender": "sample_user@example.com",
      "auth": "login",
      "username": "sample_user",
      "password": "sample_password",
      "test-email-address": "test@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/admin/smtp-settings

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

»Sample Response

{
  "data": {
    "id":"smtp",
    "type":"smtp-settings",
    "attributes": {
      "enabled": true,
      "host": "example.com",
      "port": 25,
      "sender": "sample_user@example.com",
      "auth": "login",
      "username": "sample_user"
    }
  }
}

{
  "data": {
    "id":"smtp",
    "type":"smtp-settings",
    "attributes": {
      "enabled": true,
      "host": "example.com",
      "port": 25,
      "sender": "sample_user@example.com",
      "auth": "login",
      "username": "sample_user"
    }
  }
}

»List Twilio Settings

GET /api/v2/admin/twilio-settings

StatusResponseReason
200JSON API document (type: "twilio-settings")Successfully listed Twilio settings
404JSON API error objectUser 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/admin/twilio-settings

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

»Sample Response

{
  "data": {
    "id": "twilio",
    "type": "twilio-settings",
    "attributes": {
      "enabled": true,
      "account-sid": "12345abcd",
      "from-number": "555-555-5555"
    }
  }
}

{
  "data": {
    "id": "twilio",
    "type": "twilio-settings",
    "attributes": {
      "enabled": true,
      "account-sid": "12345abcd",
      "from-number": "555-555-5555"
    }
  }
}

»Update Twilio Settings

PATCH /api/v2/admin/twilio-settings

StatusResponseReason
200JSON API document (type: "twilio-settings")Successfully listed Twilio settings
404JSON API error objectUser unauthorized to perform action
422JSON API error objectMalformed request body (missing attributes, wrong types, etc.)

»Request Body

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

If data.attributes.enabled is set to true, all remaining attributes must have valid values. You can omit attributes if they have a default value, or if a value was set by a previous update. Omitted attributes keep their previous values.

Key pathTypeDefaultDescription
data.attributes.enabledboolfalseAllows Twilio to be used. If true, all remaining attributes must have valid values.
data.attributes.account-sidstringThe Twilio account id.
data.attributes.auth-tokenstringThe Twilio authentication token.
data.attributes.from-numberstringThe Twilio registered phone number that will be used to send the message.
{
  "data": {
    "attributes": {
      "enabled": true,
      "account-sid": "12345abcd",
      "auth-token": "sample_token",
      "from-number": "555-555-5555"
    }
  }
}

{
  "data": {
    "attributes": {
      "enabled": true,
      "account-sid": "12345abcd",
      "auth-token": "sample_token",
      "from-number": "555-555-5555"
    }
  }
}

»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/admin/twilio-settings

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

»Sample Response

{
  "data": {
    "id":"twilio",
    "type":"twilio-settings",
    "attributes": {
      "enabled": true,
      "account-sid": "12345abcd",
      "from-number": "555-555-5555"
    }
  }
}

{
  "data": {
    "id":"twilio",
    "type":"twilio-settings",
    "attributes": {
      "enabled": true,
      "account-sid": "12345abcd",
      "from-number": "555-555-5555"
    }
  }
}

»Verify Twilio Settings

POST /api/v2/admin/twilio-settings/verify

Uses the test-number attribute to send a test SMS when Twilio is enabled.

StatusResponseReason
200noneTwilio test message sent successfully
400JSON API error objectVerification settings invalid (missing test number, Twilio disabled, etc.)
404JSON API error objectUser unauthorized to perform action

»Request Body

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

Key pathTypeDefaultDescription
data.attributes.test-numberstringThe target phone number for the test SMS. Not persisted and only used during testing.
{
  "data": {
    "attributes": {
      "test-number": "555-555-0000"
    }
  }
}

{
  "data": {
    "attributes": {
      "test-number": "555-555-0000"
    }
  }
}

»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/admin/twilio-settings/verify

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

»List Customization Settings

GET /api/v2/admin/customization-settings

This API endpoint is available in Terraform Enterprise as of version 202003-1.

StatusResponseReason
200JSON API document (type: "customization-settings")Successfully listed Customization settings
404JSON API error objectUser 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/admin/customization-settings

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

»Sample Response

{
  "data": {
    "id": "customization",
    "type": "customization-settings",
    "attributes": {
      "support-email-address": "support@hashicorp.com",
      "login-help": "",
      "footer": "",
      "error": "",
      "new-user": "",
    }
  }
}

{
  "data": {
    "id": "customization",
    "type": "customization-settings",
    "attributes": {
      "support-email-address": "support@hashicorp.com",
      "login-help": "",
      "footer": "",
      "error": "",
      "new-user": "",
    }
  }
}

»Update Customization Settings

PATCH /api/v2/admin/customization-settings

StatusResponseReason
200JSON API document (type: "customization-settings")Successfully updated the Customization settings
404JSON API error objectUser unauthorized to perform action
422JSON API error objectMalformed 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 pathTypeDefaultDescription
data.attributes.support-email-addressstring"support@hashicorp.com"The support address for outgoing emails.
data.attributes.login-helpstring""The login help text presented to users on the login page.
data.attributes.footerstring""Custom footer content that is added to the application.
data.attributes.errorstring""Error instruction content that is presented to users upon unexpected errors.
data.attributes.new-userstring""New user instructions that is presented when the user is not yet attached to an organization.

»Sample Payload

{
  "data": {
    "attributes": {
      "support-email-address": "support@hashicorp.com",
      "login-help": "<div>Login Help</div>",
      "footer": "<p>Custom Footer Content</p>",
      "error": "<em>Custom Error Instructions</em>",
      "new-user": "New user? <a href=\"#\">Click Here</a>",
    }
  }
}

{
  "data": {
    "attributes": {
      "support-email-address": "support@hashicorp.com",
      "login-help": "<div>Login Help</div>",
      "footer": "<p>Custom Footer Content</p>",
      "error": "<em>Custom Error Instructions</em>",
      "new-user": "New user? <a href=\"#\">Click Here</a>",
    }
  }
}

»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/admin/customization-settings

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

»Sample Response

{
  "data": {
    "id": "customization",
    "type": "customization-settings",
    "attributes": {
      "support-email-address": "support@hashicorp.com",
      "login-help": "\u003cdiv\u003eLogin Help\u003c/div\u003e",
      "footer": "\u003cp\u003eCustom Footer Content\u003c/p\u003e",
      "error": "\u003cem\u003eCustom Error Instructions\u003c/em\u003e",
      "new-user": "New user? \u003ca href=\"#\"\u003eClick Here\u003c/a\u003e",
    }
  }
}

{
  "data": {
    "id": "customization",
    "type": "customization-settings",
    "attributes": {
      "support-email-address": "support@hashicorp.com",
      "login-help": "\u003cdiv\u003eLogin Help\u003c/div\u003e",
      "footer": "\u003cp\u003eCustom Footer Content\u003c/p\u003e",
      "error": "\u003cem\u003eCustom Error Instructions\u003c/em\u003e",
      "new-user": "New user? \u003ca href=\"#\"\u003eClick Here\u003c/a\u003e",
    }
  }
}
Edit this page on GitHub