A new platform for documentation and tutorials is launching soon.
We are migrating Terraform documentation into HashiCorp Developer, our new developer experience.
Search Terraform documentation 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 SettingsGET /api/v2/admin/general-settings
» Sample Requestcurl \
--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 SettingsPATCH /api/v2/admin/general-settings
» Request BodyThis 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.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.
» 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 Requestcurl \
--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 SettingsGET /api/v2/admin/cost-estimation-settings
» Sample Requestcurl \
--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 SettingsPATCH /api/v2/admin/cost-estimation-settings
» Request BodyThis 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" ,
}
}
}
{
"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 Requestcurl \
--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 SettingsGET /api/v2/admin/saml-settings
» Sample Requestcurl \
--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 SettingsPATCH /api/v2/admin/saml-settings
» Request BodyThis 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 Identity Provider Certificate specifies the PEM encoded X.509 Certificate as provided by the IdP configuration. 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.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" ,
"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 Requestcurl \
--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 CertificatePOST /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 Requestcurl \
--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 SettingsGET /api/v2/admin/smtp-settings
» Sample Requestcurl \
--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 SettingsPATCH /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.
» Request BodyThis 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 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"
}
}
}
{
"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 Requestcurl \
--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 SettingsGET /api/v2/admin/twilio-settings
» Sample Requestcurl \
--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 SettingsPATCH /api/v2/admin/twilio-settings
» Request BodyThis 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 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"
}
}
}
{
"data" : {
"attributes" : {
"enabled" : true ,
"account-sid" : "12345abcd" ,
"auth-token" : "sample_token" ,
"from-number" : "555-555-5555"
}
}
}
» Sample Requestcurl \
--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 SettingsPOST /api/v2/admin/twilio-settings/verify
Uses the test-number
attribute to send a test SMS when Twilio is enabled.
» Request BodyThis 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"
}
}
}
{
"data" : {
"attributes" : {
"test-number" : "555-555-0000"
}
}
}
» Sample Requestcurl \
--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 SettingsGET /api/v2/admin/customization-settings
This API endpoint is available in Terraform Enterprise as of version 202003-1.
» Sample Requestcurl \
--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 SettingsPATCH /api/v2/admin/customization-settings
» Request BodyThis 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"
The support address for outgoing 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.
» 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 Requestcurl \
--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" ,
}
}
}