docs: add info about auth methods

docs/guides/2-provider-configuration.md

@@ -7,6 +7,8 @@ subcategory: "Guides"
 
 ## Example usage
 
+### API Key
+
 `main.tf`
 
 ```hcl
@@ -25,13 +27,49 @@ provider "octopusdeploy" {
 }
 ```
 
+### Access Token (via Environment Variable)
+OIDC Access Tokens are short-lived and typically generated per-run of an automated pipeline, such as GitHub Actions.
+If you use the Access Token approach, we recommend sourcing the token from environment variable.
+
+The environment variable fallback values that the Terraform Provider search for correspond to the values that pipeline steps like our [GitHub Login action](https://github.com/OctopusDeploy/login?tab=readme-ov-file#outputs) set in the pipeline context, so the provider will automatically pick up the value from environment variable.
+
+`main.tf`
+
+```hcl
+terraform {
+    required_providers {
+        octopusdeploy = {
+            source = OctopusDeployLabs/octopusdeploy
+        }
+    }
+}
+
+provider "octopusdeploy" {
+  space_id      = "..."
+}
+```
+
 ## Schema
 
 ### Required
-* `address` (String) The Octopus Deploy server URL. This can also be set using the `OCTOPUS_URL` environment variable.
-* `api_key` (String) The Octopus Deploy server API key. This can also be set using the `OCTOPUS_APIKEY` environment variable.
+* `address` (String) The Octopus Deploy server URL.
+
+and one of either
+* `api_key` (String) The Octopus Deploy server API key.
+
+OR
+* `access_token` (String) The OIDC Access Token from an OIDC exchange.
 
 ### Optional
 * `space_id` (String) The ID of the space to create the resources in.
 
-**If `space_id` is not specified the default space will be used.**
+**If `space_id` is not specified the default space will be used.**
+
+### Environment Variable fallback
+The following priority order will be used to calculate the final value for these configuration items:
+
+| Configuration Item | Priority Order                                                                                   |
+|--------------------|--------------------------------------------------------------------------------------------------|
+| `address`          | 1. Provider Configuration Block <br /> 2. env: `OCTOPUS_URL`                                     |
+| `api_key`          | 1. Provider Configuration Block <br /> 2. env: `OCTOPUS_APIKEY` <br /> 3. env: `OCTOPUS_API_KEY` |
+| `access_token`     | 1. Provider Configuration Block <br /> 2. env: `OCTOPUS_ACCESS_TOKEN`                            |

docs/index.md

@@ -17,6 +17,13 @@ This provider is used to configure resources in Octopus Deploy. The provider mus
 
 ## Configuration
 
+### Authentication Methods
+The provider supports authenticating to an Octopus Server instance via either:
+* API Key
+* OIDC Access Token
+
+These are mutually exclusive options - use either, not both. For backward compatibility, API Key will always be preferred over OIDC, when an API Key is present.
+
 ### Default Space
 
 Octopus Deploy supports the concept of a Default Space. This is the first space that is automatically created on server setup. If you do not specify a Space when configuring the Octopus Deploy Terraform provider it will use the Default Space.
@@ -81,6 +88,7 @@ resource "octopusdeploy_environment" "Env3" {
 
 ### Optional
 
+- `access_token` (String) The OIDC Access Token to use with the Octopus REST API
 - `address` (String) The endpoint of the Octopus REST API
 - `api_key` (String) The API key to use with the Octopus REST API
 - `space_id` (String) The space ID to target

templates/guides/2-provider-configuration.md.tmpl

@@ -7,6 +7,8 @@ subcategory: "Guides"
 
 ## Example usage
 
+### API Key
+
 `main.tf`
 
 ```hcl
@@ -25,13 +27,49 @@ provider "octopusdeploy" {
 }
 ```
 
+### Access Token (via Environment Variable)
+OIDC Access Tokens are short-lived and typically generated per-run of an automated pipeline, such as GitHub Actions.
+If you use the Access Token approach, we recommend sourcing the token from environment variable.
+
+The environment variable fallback values that the Terraform Provider search for correspond to the values that pipeline steps like our [GitHub Login action](https://github.com/OctopusDeploy/login?tab=readme-ov-file#outputs) set in the pipeline context, so the provider will automatically pick up the value from environment variable.
+
+`main.tf`
+
+```hcl
+terraform {
+    required_providers {
+        octopusdeploy = {
+            source = OctopusDeployLabs/octopusdeploy
+        }
+    }
+}
+
+provider "octopusdeploy" {
+  space_id      = "..."
+}
+```
+
 ## Schema
 
 ### Required
-* `address` (String) The Octopus Deploy server URL. This can also be set using the `OCTOPUS_URL` environment variable.
-* `api_key` (String) The Octopus Deploy server API key. This can also be set using the `OCTOPUS_APIKEY` environment variable.
+* `address` (String) The Octopus Deploy server URL.
+
+and one of either
+* `api_key` (String) The Octopus Deploy server API key.
+
+OR
+* `access_token` (String) The OIDC Access Token from an OIDC exchange.
 
 ### Optional
 * `space_id` (String) The ID of the space to create the resources in.
 
-**If `space_id` is not specified the default space will be used.**
+**If `space_id` is not specified the default space will be used.**
+
+### Environment Variable fallback
+The following priority order will be used to calculate the final value for these configuration items:
+
+| Configuration Item | Priority Order                                                                                   |
+|--------------------|--------------------------------------------------------------------------------------------------|
+| `address`          | 1. Provider Configuration Block <br /> 2. env: `OCTOPUS_URL`                                     |
+| `api_key`          | 1. Provider Configuration Block <br /> 2. env: `OCTOPUS_APIKEY` <br /> 3. env: `OCTOPUS_API_KEY` |
+| `access_token`     | 1. Provider Configuration Block <br /> 2. env: `OCTOPUS_ACCESS_TOKEN`                            |

templates/index.md.tmpl

@@ -17,6 +17,13 @@ This provider is used to configure resources in Octopus Deploy. The provider mus
 
 ## Configuration
 
+### Authentication Methods
+The provider supports authenticating to an Octopus Server instance via either:
+* API Key
+* OIDC Access Token
+
+These are mutually exclusive options - use either, not both. For backward compatibility, API Key will always be preferred over OIDC, when an API Key is present.
+
 ### Default Space
 
 Octopus Deploy supports the concept of a Default Space. This is the first space that is automatically created on server setup. If you do not specify a Space when configuring the Octopus Deploy Terraform provider it will use the Default Space.