Test configuration API

Use the /test-configuration API endpoint to configure dynamic credentials for registry module tests. This API allows you to enable and manage OIDC authentication for module test runs, eliminating the need for static credentials.

Configure dynamic credentials

To configure dynamic credentials, send a PATCH request to the resource at the following path:

PATCH /api/v2/registry-modules/:registry_name/:namespace/:name/:provider/test-configuration

Path parameters

Parameter	Description	Data type	Required
`registry_name`	Name of the registry, usually `private`.	String	Required
`namespace`	Namespace or organization name.	String	Required
`name`	Module name.	String	Required
`provider`	Provider name, for example `aws`, `gcp`, `azurerm`	String	Required

Request body

The request body should be a JSON object with the following structure:

{
  "data": {
    "type": "test-configurations",
    "attributes": {
      "oidc-enabled": true,
      "oidc-provider": "aws",
      "oidc-configuration": {
        // Provider-specific configuration
      }
    }
  }
}

Attributes

Attribute	Description	Data type	Required
`oidc-enabled`	Set to `true` to enable dynamic credentials.	Boolean	Required
`oidc-provider`	OIDC provider type. Accepted values: `aws`: Amazon Web Services `gcp`: Google Cloud Platform `azure`: Microsoft Azure `vault`: HashiCorp Vault	String	Required when `oidc-enabled` is `true`
`oidc-configuration`	Provider-specific configuration. Refer to: AWS configuration GPC configuration Azure configuration Vault configuration .	Object	Required when `oidc-enabled` is `true`

AWS configuration

For AWS dynamic credentials, use the following configuration:

{
  "data": {
    "type": "test-configurations",
    "attributes": {
      "oidc-enabled": true,
      "oidc-provider": "aws",
      "oidc-configuration": {
        "role-arn": "arn:aws:iam::123456789012:role/terraform-module-test-role",
        "audience": "aws.workload.identity"
      }
    }
  }
}

The AWS configuration object supports the following attributes:

Attribute	Description	Data type	Required
`role-arn`	ARN of the IAM role to assume.	String	Required
`audience`	Audience claim for the OIDC token. Defaults to `aws.workload.identity`	String	Optional

GCP configuration

For GCP dynamic credentials, use the following configuration:

{
  "data": {
    "type": "test-configurations",
    "attributes": {
      "oidc-enabled": true,
      "oidc-provider": "gcp",
      "oidc-configuration": {
        "service-account-email": "terraform-module-test-sa@my-project.iam.gserviceaccount.com",
        "workload-provider-name": "projects/123456789/locations/global/workloadIdentityPools/terraform-module-tests/providers/terraform-cloud",
        "audience": "gcp.workload.identity"
      }
    }
  }
}

GCP Configuration Attributes:

service-account-email (string, required): The email address of the service account to impersonate
workload-provider-name (string, required): The full workload identity provider name
audience (string, optional): The audience claim for the OIDC token. Defaults to gcp.workload.identity

Azure Configuration

For Azure dynamic credentials, use the following configuration:

{
  "data": {
    "type": "test-configurations",
    "attributes": {
      "oidc-enabled": true,
      "oidc-provider": "azure",
      "oidc-configuration": {
        "tenant-id": "00000000-0000-0000-0000-000000000000",
        "client-id": "11111111-1111-1111-1111-111111111111",
        "subscription-id": "22222222-2222-2222-2222-222222222222",
        "audience": "azure.workload.identity"
      }
    }
  }
}

Azure Configuration Attributes:

tenant-id (string, required): The Azure AD tenant ID
client-id (string, required): The Azure AD application (client) ID
subscription-id (string, required): The Azure subscription ID
audience (string, optional): The audience claim for the OIDC token. Defaults to azure.workload.identity

Vault Configuration

For Vault dynamic credentials, use the following configuration:

{
  "data": {
    "type": "test-configurations",
    "attributes": {
      "oidc-enabled": true,
      "oidc-provider": "vault",
      "oidc-configuration": {
        "url": "https://vault.example.com:8200",
        "role-name": "module-tests",
        "namespace": "terraform-tests",
        "auth-path": "jwt",
        "audience": "vault.workload.identity"
      }
    }
  }
}

Vault Configuration Attributes:

url (string, required): The Vault instance URL
role-name (string, required): The name of the JWT auth role in Vault
namespace (string, optional): The Vault namespace (Vault Enterprise only)
auth-path (string, optional): The path where the JWT auth method is mounted. Defaults to jwt
audience (string, optional): The audience claim for the OIDC token. Defaults to vault.workload.identity

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/registry-modules/private/my-org/vpc/aws/test-configuration

Sample Response

{
  "data": {
    "id": "modconf-abc123xyz",
    "type": "test-configurations",
    "attributes": {
      "oidc-enabled": true,
      "oidc-provider": "aws",
      "created-at": "2025-01-15T10:30:00.000Z",
      "updated-at": "2025-01-15T10:30:00.000Z"
    },
    "relationships": {
      "registry-module": {
        "data": {
          "id": "mod-abc123xyz",
          "type": "registry-modules"
        }
      }
    },
    "links": {
      "self": "/api/v2/registry-modules/private/my-org/vpc/aws/test-configuration"
    }
  }
}

Note: The response does not include the OIDC configuration details for security reasons. Sensitive configuration like role ARNs and service account emails are not returned in API responses.

Retrieve test configuration

GET /api/v2/registry-modules/:registry_name/:namespace/:name/:provider/test-configuration

Retrieve the current test configuration for a registry module, including whether dynamic credentials are enabled and which provider is configured.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/registry-modules/private/my-org/vpc/aws/test-configuration

Sample Response

{
  "data": {
    "id": "modconf-abc123xyz",
    "type": "test-configurations",
    "attributes": {
      "oidc-enabled": true,
      "oidc-provider": "aws",
      "created-at": "2025-01-15T10:30:00.000Z",
      "updated-at": "2025-01-15T10:30:00.000Z"
    },
    "relationships": {
      "registry-module": {
        "data": {
          "id": "mod-abc123xyz",
          "type": "registry-modules"
        }
      }
    },
    "links": {
      "self": "/api/v2/registry-modules/private/my-org/vpc/aws/test-configuration"
    }
  }
}

Disable dynamic credentials

To disable dynamic credentials, set oidc-enabled to false:

{
  "data": {
    "type": "test-configurations",
    "attributes": {
      "oidc-enabled": false
    }
  }
}

When disabling dynamic credentials, you don't need to include the oidc-provider or oidc-configuration attributes.

Update organization token TTL

Configure the default token time-to-live (TTL) for module test runs at the organization level using the Organizations API.

PATCH /api/v2/organizations/:organization_name

Request Body

{
  "data": {
    "type": "organizations",
    "attributes": {
      "module-test-token-ttl": 900
    }
  }
}

Attributes

module-test-token-ttl (integer, optional): The token TTL in seconds. Valid range is 300 to 1800 seconds (5 to 30 minutes). Defaults to 600 seconds (10 minutes).

Sample Request

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

With payload.json:

{
  "data": {
    "type": "organizations",
    "attributes": {
      "module-test-token-ttl": 900
    }
  }
}

Sample Response

{
  "data": {
    "id": "org-abc123xyz",
    "type": "organizations",
    "attributes": {
      "name": "my-org",
      "module-test-token-ttl": 900,
      // ... other organization attributes
    }
  }
}

Error responses

If the payload or call is malformed or contains invalid data, the API returns the following error responses.

Invalid provider

If you specify an invalid OIDC provider:

{
  "errors": [
    {
      "status": "422",
      "title": "Invalid Attribute",
      "detail": "OIDC provider must be one of: aws, gcp, azure, vault",
      "source": {
        "pointer": "/data/attributes/oidc-provider"
      }
    }
  ]
}

Missing configuration

If you enable OIDC without providing configuration:

{
  "errors": [
    {
      "status": "422",
      "title": "Invalid Attribute",
      "detail": "OIDC configuration is required when OIDC is enabled",
      "source": {
        "pointer": "/data/attributes/oidc-configuration"
      }
    }
  ]
}

Invalid token TTL

If you specify a token TTL outside the valid range:

{
  "errors": [
    {
      "status": "422",
      "title": "Invalid Attribute",
      "detail": "Module test token TTL must be between 300 and 1800 seconds",
      "source": {
        "pointer": "/data/attributes/module-test-token-ttl"
      }
    }
  ]
}

Not found

If the registry module doesn't exist:

{
  "errors": [
    {
      "status": "404",
      "title": "Not Found",
      "detail": "Registry module not found"
    }
  ]
}

Unauthorized

If you don't have permission to modify the test configuration:

{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "detail": "You do not have permission to modify this module's test configuration"
    }
  ]
}