Terraform Enterprise Settings API

This topic provides reference information for the following endpoints:

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

Status	Response	Reason
200	JSON API document (`type: "general-settings"`)	Successfully listed General settings
404	JSON API error object	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/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,
      "plan-timeout": "2h",
      "apply-timeout": "24h",
      "send-passing-statuses-for-untriggered-speculative-plans": false,
      "allow-speculative-plans-on-pull-requests-from-forks": false,
      "default-remote-state-access": true,
      "enable-public-registration": false
    }
  }
}

Update General Settings

PATCH /api/v2/admin/general-settings

Status	Response	Reason
200	JSON API document (`type: "general-settings"`)	Successfully updated the General settings
404	JSON API error object	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.attributes.allow-speculative-plans-on-pull-requests-from-forks`	bool	`false`	When 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-limit`	integer	30	The 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-enabled`	bool	`true`	Whether 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-access`	bool	`true`	Determines 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.enable-public-registration`	bool	`false`	Determines whether unauthenticated users can create accounts from the public sign-up page. Email invitations, Security Assertion Markup Language (SAML) just-in-time provisioning, and System for Cross-domain Identity Management (SCIM) provisioning continue to work regardless of this setting. To preserve open-registration behavior after upgrading from a version without this setting, explicitly set this value to `true`. Refer to Administration: General Settings.
`data.attributes.limit-user-organization-creation`	bool	`true`	When 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-plans`	bool	`false`	When set to `true`, workspaces automatically send passing commit statuses for any pull requests that don't affect their tracked files.
`data.attributes.plan-timeout`	string	`2h`	Default maximum run time for Terraform plans. Can be overridden on a per-organization basis. Specify a duration with a decimal number and a unit suffix.
`data.attributes.apply-timeout`	string	`24h`	Default maximum run time for Terraform applies. Can be overridden on a per-organization basis. Specify a duration with a decimal number and a unit suffix.
`data.attributes.terraform-build-worker-plan-timeout`	string	`2h`	Deprecated. Please use `data.attributes.plan-timeout` instead.
`data.attributes.terraform-build-worker-apply-timeout`	string	`24h`	Deprecated. Please use `data.attributes.apply-timeout` instead.

Sample Payload

{
  "data": {
    "attributes": {
      "limit-user-organization-creation": true,
      "api-rate-limiting-enabled": true,
      "api-rate-limit": 50,
      "enable-public-registration": true,
      "plan-timeout": "2h",
      "apply-timeout": "24h"
    }
  }
}

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

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,
      "plan-timeout": "2h",
      "apply-timeout": "24h",
      "default-remote-state-access": true,
      "enable-public-registration": true
    }
  }
}

Show data retention policy settings

GET /api/v2/admin/data-retention-policy-settings

This endpoint returns the global data retention policy for all organizations. When a global data retention policy is not set, organizations retain all backing data by default. Read more about admin data retention policy settings.

Admin settings only support the data-retention-policy-delete-olders policy type.

Refer to Data Retention Policy API for details.

Create or update data retention policy settings

POST /api/v2/admin/data-retention-policy-settings

This endpoint creates a default data retention policy for all organizations on the site. When a global data retention policy is not set, organizations retain all backing data by default. Read more about admin data retention policy settings.

Admin settings only support the data-retention-policy-delete-olders policy type.

Refer to Data Retention Policy API for details.

Remove data retention policy

DELETE /api/v2/admin/data-retention-policy-settings

This endpoint removes the data retention policy set at the site admin level. When a data retention policy is not set for the site admin, organizations retain all backing data by default.

Read more about admin data retention policy settings.

See Data Retention Policy API for details.

List Cost Estimation Settings

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

Status	Response	Reason
200	JSON API document (`type: "cost-estimation-settings"`)	Successfully listed Cost Estimation settings
404	JSON API error object	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/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"
    }
  }
}

Update Cost Estimation Settings

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

Status	Response	Reason
200	JSON API document (`type: "cost-estimation-settings"`)	Successfully updated Cost Estimation settings
404	JSON API error object	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.

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 path	Type	Default	Description
`data.attributes.enabled`	bool	`false`	Allows organizations to opt-in to the Cost Estimation feature.
`data.attributes.aws-access-key-id`	string		An AWS Access Key ID that the Cost Estimation feature will use to authorize to AWS's Pricing API.
`data.attributes.aws-secret-key`	string		An AWS Secret Key that the Cost Estimation feature will use to authorize to AWS's Pricing API.
`data.attributes.gcp-credentials`	string		A 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-id`	string		An Azure Client ID that the Cost Estimation feature will use to authorize to Azure's RateCard API.
`data.attributes.azure-client-secret`	string		An Azure Client Secret that the Cost Estimation feature will use to authorize to Azure's RateCard API.
`data.attributes.azure-subscription-id`	string		An Azure Subscription ID that the Cost Estimation feature will use to authorize to Azure's RateCard API.
`data.attributes.azure-tenant-id`	string		An 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"
    }
  }
}

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

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"
    }
  }
}

List SAML Settings

Deprecation warning: The idp-cert and old-idp-cert attributes are deprecated and will be removed from future versions of the API. Use the SAML IdP Certificates API to manage IdP certificates.

GET /api/v2/admin/saml-settings

Status	Response	Reason
200	JSON API document (`type: "saml-settings"`)	Successfully listed SAML settings
404	JSON API error object	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/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",
      "attr-site-auditor": "SiteAuditor",
      "site-auditor-role": "site-auditors",
      "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

Deprecation warning: The idp-cert attribute is deprecated and will be removed from future versions of the API. Use the SAML IdP Certificates API to manage IdP certificates.

PATCH /api/v2/admin/saml-settings

Status	Response	Reason
200	JSON API document (`type: "saml-settings"`)	Successfully updated SAML settings
404	JSON API error object	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.

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 path	Type	Default	Description
`data.attributes.enabled`	bool	`false`	Allows SAML to be used. If true, all remaining attributes must have valid values.
`data.attributes.debug`	bool	`false`	Enables a SAML debug dialog that allows an admin to see the SAMLResponse XML and processed values during login.
`data.attributes.idp-cert`	string		Deprecated. Identity Provider Certificate specifies the PEM encoded X.509 Certificate as provided by the IdP configuration. Setting this attribute rotates the legacy certificate slots: Terraform Enterprise moves the current `idp-cert` value to `old-idp-cert` and stores the new value as `idp-cert`. If `old-idp-cert` is already populated, Terraform Enterprise discards the current `idp-cert` value instead and leaves `old-idp-cert` unchanged. Use the SAML IdP Certificates API instead.
`data.attributes.slo-endpoint-url`	string		Single 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-url`	string		Single 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-username`	string	`"Username"`	Username Attribute Name specifies the name of the SAML attribute that determines the user's username.
`data.attributes.attr-groups`	string	`"MemberOf"`	Team Attribute Name specifies the name of the SAML attribute that determines team membership.
`data.attributes.attr-site-admin`	string	`"SiteAdmin"`	Specifies the role for site admin access. Overrides the "Site Admin Role" method.
`data.attributes.site-admin-role`	string	`"site-admins"`	Specifies the role for site admin access, provided in the list of roles sent in the Team Attribute Name attribute.
`data.attributes.attr-site-auditor`	string	`"SiteAuditor"`	Specifies the attribute for Site Auditor access. Overrides the "Site Auditor Role" method.
`data.attributes.site-auditor-role`	string	`"site-auditors"`	Specifies the role for Site Auditor access, provided in the list of roles sent in the Team Attribute Name attribute.
`data.attributes.sso-api-token-session-timeout`	integer	1209600	Specifies 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",
      "attr-site-auditor": "SiteAuditor",
      "site-auditor-role": "site-auditors",
      "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

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",
      "attr-site-auditor": "SiteAuditor",
      "site-auditor-role": "site-auditors",
      "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

Deprecation warning: This endpoint is deprecated and will be removed from future versions of the API. Use Delete a SAML IdP certificate instead.

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

When you rotate the deprecated idp-cert attribute, Terraform Enterprise retains the old IdP certificate to allow for a rotation period. This endpoint revokes the older IdP certificate when the new IdP certificate is known to be functioning correctly. This endpoint only affects the old-idp-cert slot and never removes a certificate that you added with the SAML IdP Certificates API.

Status	Response	Reason
200	JSON API document (`type: "saml-settings"`)	Successfully revoked the old IdP certificate
400	JSON API error object	SAML is not enabled, or there is no old certificate to revoke
404	JSON API error object	User unauthorized to perform action

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

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"
    }
  }
}

SAML IdP Certificates

Refer to SAML IdP Certificates API for endpoints to list, inspect, add, update, download, delete, and validate the IdP certificates that Terraform Enterprise trusts. Terraform Enterprise can trust multiple IdP certificates at the same time, which supports multi-region identity providers, identity provider migrations, and zero-downtime certificate rotation.

SCIM Settings

Refer to SCIM Settings API for endpoints to enable, update, and disable SCIM provisioning settings.

List SMTP Settings

GET /api/v2/admin/smtp-settings

Status	Response	Reason
200	JSON API document (`type: "smtp-settings"`)	Successfully listed SMTP settings
404	JSON API error object	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/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"
    }
  }
}

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.

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

Request Body

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

Key path	Type	Default	Description
`data.attributes.enabled`	bool	`false`	Allows SMTP to be used. If true, all remaining attributes must have valid values.
`data.attributes.host`	string		The host address of the SMTP server.
`data.attributes.port`	integer		The port of the SMTP server.
`data.attributes.sender`	string		The desired sender address.
`data.attributes.auth`	string	`"none"`	The authentication type. Valid values are `"none"`, `"plain"`, and `"login"`.
`data.attributes.username`	string		The username used to authenticate to the SMTP server. Only required if `data.attributes.auth` is set to `"login"` or `"plain"`.
`data.attributes.password`	string		The username used to authenticate to the SMTP server. Only required if `data.attributes.auth` is set to `"login"` or `"plain"`.
`data.attributes.test-email-address`	string		The 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"
    }
  }
}

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

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"
    }
  }
}

List Twilio Settings

GET /api/v2/admin/twilio-settings

Status	Response	Reason
200	JSON API document (`type: "twilio-settings"`)	Successfully listed Twilio settings
404	JSON API error object	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/admin/twilio-settings

Sample Response

{
  "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

Status	Response	Reason
200	JSON API document (`type: "twilio-settings"`)	Successfully listed Twilio settings
404	JSON API error object	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.attributes.enabled`	bool	`false`	Allows Twilio to be used. If true, all remaining attributes must have valid values.
`data.attributes.account-sid`	string		The Twilio account id.
`data.attributes.auth-token`	string		The Twilio authentication token.
`data.attributes.from-number`	string		The 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"
    }
  }
}

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

Sample Response

{
  "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.

Status	Response	Reason
200	none	Twilio test message sent successfully
400	JSON API error object	Verification settings invalid (missing test number, Twilio disabled, etc.)
404	JSON API error object	User unauthorized to perform action

Request Body

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

Key path	Type	Default	Description
`data.attributes.test-number`	string		The target phone number for the test SMS. Not persisted and only used during testing.

{
  "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

List Customization Settings

GET /api/v2/admin/customization-settings

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

Status	Response	Reason
200	JSON API document (`type: "customization-settings"`)	Successfully listed Customization settings
404	JSON API error object	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/admin/customization-settings

Sample Response

Note that the support-email-address attribute in the following example returns support@hashicorp.com, which is a not a functional email address. If you need assistance, visit the HashiCorp support page and open a ticket.

{
  "data": {
    "id": "customization",
    "type": "customization-settings",
    "attributes": {
      "support-email-address": "support@hashicorp.com",
      "login-help": "",
      "footer": "",
      "error": "",
      "new-user": "",
      "internal-support-url": "",
      "internal-documentation-url": "",
      "internal-tutorials-url": "",
      "avatar-sources": [
        { "source": "gravatar", "enabled": true }
      ]
    }
  }
}

Update Customization Settings

PATCH /api/v2/admin/customization-settings

Status	Response	Reason
200	JSON API document (`type: "customization-settings"`)	Successfully updated the Customization settings
404	JSON API error object	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.attributes.support-email-address`	string	`"support@hashicorp.com"` Note that this is a non-functional address. If you need assistance, visit the HashiCorp support page and open a ticket.	The support address for outgoing system emails.
`data.attributes.login-help`	string	`""`	The login help text presented to users on the login page.
`data.attributes.footer`	string	`""`	Custom footer content that is added to the application.
`data.attributes.error`	string	`""`	Error instruction content that is presented to users upon unexpected errors.
`data.attributes.new-user`	string	`""`	New user instructions that is presented when the user is not yet attached to an organization.
`data.attributes.internal-support-url`	string	`"https://support.ibm.com"`	The URL for support links in the Terraform Enterprise UI (Help menu and error pages). When set, overrides the default. Accepts `https://`, `http://`, or `mailto:` schemes. Maximum 2048 characters.
`data.attributes.internal-documentation-url`	string	`"https://developer.hashicorp.com/terraform/enterprise"`	The URL for documentation links in the Terraform Enterprise UI (Help menu). When set, overrides the default. Accepts `https://` or `http://` schemes. Maximum 2048 characters.
`data.attributes.internal-tutorials-url`	string	`"https://developer.hashicorp.com/terraform/tutorials"`	The URL for tutorial links in the Terraform Enterprise UI (Help menu). When set, overrides the default. Accepts `https://` or `http://` schemes. Maximum 2048 characters.
`data.attributes.avatar-sources`	array of objects	`[{"source":"gravatar","enabled":true}]`	Controls which external avatar services are enabled. Refer to Avatar sources for more information.
`data.attributes.avatar-sources.source`	string	`"gravatar"`	Specifies the source of the avatar service. The only accepted value is `"gravatar"`.
`data.attributes.avatar-sources.enabled`	boolean	`true`	Determines whether an external avatar service is enabled. When disabled, Terraform Enterprise does not generate Gravatar URLs for any user and falls back to text initials. Terraform Enterprise sources up to two characters from the local part of the user's email address rendered in a colored square. If no email is set, Terraform Enterprise sources text initials from their username instead. Text initials are always the terminal fallback. You cannot use this field to disable the fallback.

Sample Payload

In the following example, the support-email-address attribute specifies support@hashicorp.com, which is not a functional email address. If you need assistance, visit the HashiCorp support page and open a ticket.

{
  "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>",
      "internal-support-url": "https://support.example.com",
      "internal-documentation-url": "https://docs.example.com",
      "internal-tutorials-url": "https://learn.example.com",
      "avatar-sources": [
        { "source": "gravatar", "enabled": false }
      ]
    }
  }
}

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

Sample Response

In the following example, the support-email-address attribute specifies support@hashicorp.com, which is a not a functional address. If you need assistance, visit the HashiCorp support page and open a ticket.

{
  "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",
      "internal-support-url": "https://support.example.com",
      "internal-documentation-url": "https://docs.example.com",
      "internal-tutorials-url": "https://learn.example.com",
      "avatar-sources": [
        { "source": "gravatar", "enabled": false }
      ]
    }
  }
}

Announcement banners

Announcement banners let Terraform Enterprise administrators broadcast a site-wide message, such as an upcoming maintenance window or an ongoing incident. Refer to Customize the UI for instructions about managing banners in the UI.

Terraform Enterprise supports one non-deactivated banner at a time. To replace a banner, deactivate the existing banner before you create a new one. This requirement applies to any non-deactivated banner, including a banner with a future schedule.

The banner endpoints use the admin-banners resource type, which contains the following attributes.

Key path	Type	Description
`data.type`	string	Required. Must be `"admin-banners"`.
`data.attributes.title`	string	Required. The heading of the banner. Maximum 100 characters.
`data.attributes.body`	string	Required. The message of the banner. Maximum 500 characters after sanitization. Supports the same HTML formatting as the other customization settings, including common formatting such as bold, italic, links, lists, headings, and code. Terraform Enterprise sanitizes the supplied content before it stores it. Scripts, inline styles, form controls, event handlers, and unsafe URLs are removed. The body must retain at least one displayable character after sanitization.
`data.attributes.style`	string	Required. The visual style of the banner. Must be `info`, `warning`, or `critical`.
`data.attributes.audience`	string	Required. Determines who sees the banner. Specify `all_users` to include visitors who have not signed in, such as visitors on the login page. Specify `authenticated_only` to restrict the banner to users who have signed in.
`data.attributes.scheduled-publish-at`	string	The ISO 8601 timestamp after which Terraform Enterprise displays the banner. Must be provided together with `scheduled-expire-at` and `timezone`.
`data.attributes.scheduled-expire-at`	string	The ISO 8601 timestamp after which Terraform Enterprise stops displaying the banner. It does not deactivate the banner record. Must be later than `scheduled-publish-at`, and must be provided together with `scheduled-publish-at` and `timezone`.
`data.attributes.timezone`	string	The timezone for the scheduled times, such as `America/New_York` or `UTC`. Terraform Enterprise accepts the IANA identifiers that Rails recognizes, which retain the older spelling for zones that have since been renamed. For example, specify `Europe/Kiev` rather than `Europe/Kyiv`. An unrecognized value returns a `422` response. Must be provided together with `scheduled-publish-at` and `scheduled-expire-at`.
`data.attributes.published-at`	string	Read only. The timestamp when Terraform Enterprise creates or saves an unscheduled banner. Scheduled banners retain `null` until you remove their schedule.

Terraform Enterprise validates the schedule as a complete set. When creating a banner, provide scheduled-publish-at, scheduled-expire-at, and timezone together, or omit all three.

When updating a banner, you can omit the schedule attributes from the request to leave the existing schedule in place. To clear the schedule, specify null for scheduled-publish-at, scheduled-expire-at, and timezone.

Specifying a partial schedule returns a 422 response. When a banner has no schedule, Terraform Enterprise publishes it immediately and keeps it active until you deactivate it.

List announcement banners

GET /api/v2/admin/banners

This endpoint returns every banner that is not deactivated, regardless of its schedule. Banners that are scheduled but not yet published are included so that you can edit or cancel them. To retrieve the banners that users currently see, use Retrieve active announcement banners instead.

Status	Response	Reason
200	JSON API document (`type: "admin-banners"`)	Successfully listed banners. The array is empty when no banner exists.
401	JSON API error object	Request is not authenticated
404	JSON API error object	User unauthorized to perform action

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://tfe.example.com/api/v2/admin/banners

Sample response

{
  "data": [
    {
      "id": "ab-Yfha4YpPidxpBmWn",
      "type": "admin-banners",
      "attributes": {
        "title": "Scheduled maintenance",
        "body": "Terraform Enterprise is unavailable on Saturday from 02:00 to 04:00 UTC. \u003ca href=\"https://status.example.com\"\u003eView status\u003c/a\u003e",
        "style": "warning",
        "audience": "all_users",
        "scheduled-publish-at": null,
        "scheduled-expire-at": null,
        "timezone": null,
        "published-at": "2026-09-08T14:31:00.000Z"
      }
    }
  ]
}

Retrieve active announcement banners

GET /api/v2/banners

This endpoint returns the banners that Terraform Enterprise currently displays. It evaluates the schedule at request time and excludes banners whose scheduled-publish-at has not passed or whose scheduled-expire-at has already passed.

This endpoint does not require authentication, so that clients can retrieve banners before a user signs in. Terraform Enterprise filters the response by audience. Unauthenticated requests receive only all_users banners and authenticated requests receive all active banners.

Status	Response	Reason
200	JSON API document (`type: "admin-banners"`)	Successfully retrieved active banners. The array is empty when none are active.

Sample request

curl \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://tfe.example.com/api/v2/banners

Sample response

{
  "data": [
    {
      "id": "ab-Yfha4YpPidxpBmWn",
      "type": "admin-banners",
      "attributes": {
        "title": "Scheduled maintenance",
        "body": "Terraform Enterprise is unavailable on Saturday from 02:00 to 04:00 UTC.",
        "style": "warning",
        "audience": "all_users",
        "scheduled-publish-at": null,
        "scheduled-expire-at": null,
        "timezone": null,
        "published-at": "2026-09-08T14:31:00.000Z"
      }
    }
  ]
}

POST /api/v2/admin/banners

You can only activate one banner at a time. Deactivate an existing banner before creating a replacement. When you omit the schedule attributes, Terraform Enterprise publishes the banner immediately. Refer to Define the banner schedule for more information.

If an activated banner already exists, even if the banner is scheduled to publish later, Terraform Enterprise returns a 409 response. The existing banner also remains unchanged.

Status	Response	Reason
201	JSON API document (`type: "admin-banners"`)	Successfully created the banner
404	JSON API error object	User unauthorized to perform action
409	JSON API error object	An active banner already exists
422	JSON API error object	Malformed request body (missing attributes, wrong types, etc.)

Request body

This POST endpoint requires a JSON object with the properties described in Announcement banners as a request payload.

Sample payload

{
  "data": {
    "type": "admin-banners",
    "attributes": {
      "title": "Scheduled maintenance",
      "body": "Terraform Enterprise is unavailable on Saturday from 02:00 to 04:00 UTC.",
      "style": "warning",
      "audience": "all_users",
      "scheduled-publish-at": "2026-09-12T02:00:00Z",
      "scheduled-expire-at": "2026-09-12T04:00:00Z",
      "timezone": "UTC"
    }
  }
}

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://tfe.example.com/api/v2/admin/banners

Sample response

{
  "data": {
    "id": "ab-Yfha4YpPidxpBmWn",
    "type": "admin-banners",
    "attributes": {
      "title": "Scheduled maintenance",
      "body": "Terraform Enterprise is unavailable on Saturday from 02:00 to 04:00 UTC.",
      "style": "warning",
      "audience": "all_users",
      "scheduled-publish-at": "2026-09-12T02:00:00.000Z",
      "scheduled-expire-at": "2026-09-12T04:00:00.000Z",
      "timezone": "UTC",
      "published-at": null
    }
  }
}

PATCH /api/v2/admin/banners/:banner_id

Parameter	Description
`:banner_id`	The ID of the banner to update, such as `ab-Yfha4YpPidxpBmWn`.

This endpoint supports partial updates. Terraform Enterprise modifies only the attributes present in the request body and applies the same validations as the create endpoint, including the schedule requirement.

Status	Response	Reason
200	JSON API document (`type: "admin-banners"`)	Successfully updated the banner
404	JSON API error object	Banner 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 properties described in Announcement banners as a request payload.

Sample payload

{
  "data": {
    "type": "admin-banners",
    "attributes": {
      "style": "critical",
      "body": "Maintenance is running longer than expected."
    }
  }
}

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://tfe.example.com/api/v2/admin/banners/ab-Yfha4YpPidxpBmWn

Sample response

{
  "data": {
    "id": "ab-Yfha4YpPidxpBmWn",
    "type": "admin-banners",
    "attributes": {
      "title": "Scheduled maintenance",
      "body": "Maintenance is running longer than expected.",
      "style": "critical",
      "audience": "all_users",
      "scheduled-publish-at": "2026-09-12T02:00:00.000Z",
      "scheduled-expire-at": "2026-09-12T04:00:00.000Z",
      "timezone": "UTC",
      "published-at": null
    }
  }
}

DELETE /api/v2/admin/banners/:banner_id

Parameter	Description
`:banner_id`	The ID of the banner to deactivate, such as `ab-Yfha4YpPidxpBmWn`.

This endpoint deactivates the banner. Terraform Enterprise retains the banner record for audit history and stops displaying the banner to users.

Status	Response	Reason
204	none	Successfully deactivated the banner
404	JSON API error object	Banner 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://tfe.example.com/api/v2/admin/banners/ab-Yfha4YpPidxpBmWn

Rotate OIDC Signing Key

POST /api/v2/admin/oidc-settings/actions/rotate-key

This endpoint rotates the OIDC signing key used for signing tokens issued for dynamic provider credentials. This key automatically rotates every 90 days, hitting this endpoint resets this timer. Hitting this endpoint has no effect on the next trim time. This endpoint should only be used if a leak of the key is suspected.

Status	Response	Reason
204	none	Successfully rotated key
422	JSON API error object	Malformed request body (missing attributes, wrong types, etc.)

Sample Request

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

Trim OIDC Signing Key

POST /api/v2/admin/oidc-settings/actions/trim-key

This endpoint trims the OIDC signing key used for signing tokens issued for dynamic provider credentials. This key automatically trims old versions 30 days after the last rotation, hitting this endpoint resets this timer. Hitting this endpoint has no effect on the next rotation time. This endpoint should only be used after rotating the key if a leak of the key is suspected.

Status	Response	Reason
204	none	Successfully trimmed key
422	JSON API error object	Malformed request body (missing attributes, wrong types, etc.)

Sample Request

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

Terraform Enterprise Settings API

List General Settings

Sample Request

Sample Response

Update General Settings

Request Body

Sample Payload

Sample Request

Sample Response

Show data retention policy settings

Create or update data retention policy settings

Remove data retention policy

List Cost Estimation Settings

Sample Request

Sample Response

Update Cost Estimation Settings

Request Body

Sample Request

Sample Response

List SAML Settings

Sample Request

Sample Response

Update SAML Settings

Request Body

Sample Request

Sample Response

Revoke previous SAML IdP Certificate

Sample Request

Sample Response

SAML IdP Certificates

SCIM Settings

List SMTP Settings

Sample Request

Sample Response

Update SMTP Settings

Request Body

Sample Payload

Sample Request

Sample Response

List Twilio Settings

Sample Request

Sample Response

Update Twilio Settings

Request Body

Sample Request

Sample Response

Verify Twilio Settings

Request Body

Sample Request

List Customization Settings

Sample Request

Sample Response

Update Customization Settings

Request Body

Sample Payload

Sample Request

Sample Response

Announcement banners

Define the banner schedule

List announcement banners

Sample request

Sample response

Retrieve active announcement banners

Sample request

Sample response

Create announcement banner

Request body

Sample payload

Sample request

Sample response

Update announcement banner

Request body

Sample payload

Sample request

Sample response

Deactivate announcement banner

Sample request

Rotate OIDC Signing Key

Sample Request

Trim OIDC Signing Key