Merge pull request #20 from ory/chore/feedback_updates

chore: adding some fixes

Author: KT-Doan

README.md

@@ -39,7 +39,7 @@ A Terraform provider for managing [Ory Network](https://www.ory.sh/) resources u
 terraform {
   required_providers {
     ory = {
-      source  = "ory/terraform-provider-orynetwork"
+      source  = "ory/orynetwork"
       version = "~> 0.1"
     }
   }
@@ -60,7 +60,7 @@ Then configure Terraform to use the local provider:
 # ~/.terraformrc
 provider_installation {
   dev_overrides {
-    "ory/terraform-provider-orynetwork" = "/path/to/terraform-provider-orynetwork"
+    "ory/orynetwork" = "/path/to/terraform-provider-orynetwork"
   }
   direct {}
 }
@@ -101,7 +101,7 @@ provider "ory" {
 terraform {
   required_providers {
     ory = {
-      source = "ory/terraform-provider-orynetwork"
+      source = "ory/orynetwork"
     }
   }
 }

docs/index.md

@@ -1,19 +1,7 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "ory Provider"
 description: |-
-  The Ory provider enables Terraform to manage Ory Network https://www.ory.sh/ resources.
-  Authentication
-  Ory Network uses two types of API keys:
-  Workspace API Key (ory_wak_...): For organizations, projects, and workspace managementProject API Key (ory_pat_...): For identities, OAuth2 clients, and sessions
-  Configure via environment variables or provider block:
-  
-  provider "ory" {
-    workspace_api_key = var.ory_workspace_key  # or ORY_WORKSPACE_API_KEY env var
-    project_api_key   = var.ory_project_key    # or ORY_PROJECT_API_KEY env var
-    project_id        = var.ory_project_id     # or ORY_PROJECT_ID env var
-    project_slug      = var.ory_project_slug   # or ORY_PROJECT_SLUG env var
-  }
+  The Ory provider enables Terraform to manage Ory Network resources.
 ---
 
 # ory Provider
@@ -24,24 +12,44 @@ The Ory provider enables Terraform to manage [Ory Network](https://www.ory.sh/)
 
 Ory Network uses two types of API keys:
 
-1. **Workspace API Key** (`ory_wak_...`): For organizations, projects, and workspace management
-2. **Project API Key** (`ory_pat_...`): For identities, OAuth2 clients, and sessions
+| API Key Type | Prefix | Used For |
+|--------------|--------|----------|
+| **Workspace API Key** | `ory_wak_...` | Projects, organizations, workspace management, project config, actions |
+| **Project API Key** | `ory_pat_...` | Identities, OAuth2 clients, relationships |
+
+## Configuration Options
+
+There are two ways to configure the Ory provider:
+
+### Option 1: Environment Variables (Recommended for CI/CD)
+
+Set credentials as environment variables and use an empty provider block:
 
-Configure via environment variables or provider block:
+```bash
+export ORY_WORKSPACE_API_KEY="ory_wak_..."
+export ORY_WORKSPACE_ID="..."           # Required for creating new projects
+export ORY_PROJECT_API_KEY="ory_pat_..."
+export ORY_PROJECT_ID="..."
+export ORY_PROJECT_SLUG="..."
+```
 
 ```hcl
-provider "ory" {
-  workspace_api_key = var.ory_workspace_key  # or ORY_WORKSPACE_API_KEY env var
-  project_api_key   = var.ory_project_key    # or ORY_PROJECT_API_KEY env var
-  project_id        = var.ory_project_id     # or ORY_PROJECT_ID env var
-  project_slug      = var.ory_project_slug   # or ORY_PROJECT_SLUG env var
+terraform {
+  required_providers {
+    ory = {
+      source = "ory/orynetwork"
+    }
+  }
 }
+
+provider "ory" {}  # Picks up from ORY_* environment variables
 ```
 
-## Example Usage
+### Option 2: Terraform Variables (Recommended for tfvars)
+
+Define variables and pass values via `terraform.tfvars` or `-var` flags:
 
-```terraform
-# Configure the Ory provider
+```hcl
 terraform {
   required_providers {
     ory = {
@@ -50,35 +58,25 @@ terraform {
   }
 }
 
-# Basic configuration using environment variables
 provider "ory" {
-  # Workspace API key for project/organization management
-  workspace_api_key = var.ory_workspace_api_key # or set ORY_WORKSPACE_API_KEY env var
-
-  # Project API key for identity/OAuth2 operations
-  project_api_key = var.ory_project_api_key # or set ORY_PROJECT_API_KEY env var
-
-  # Project identifiers
-  project_id   = var.ory_project_id   # or set ORY_PROJECT_ID env var
-  project_slug = var.ory_project_slug # or set ORY_PROJECT_SLUG env var
+  workspace_api_key = var.ory_workspace_api_key
+  workspace_id      = var.ory_workspace_id
+  project_api_key   = var.ory_project_api_key
+  project_id        = var.ory_project_id
+  project_slug      = var.ory_project_slug
 }
 
-# Configuration with custom API URLs (for staging/enterprise environments)
-# provider "ory" {
-#   workspace_api_key = var.ory_workspace_api_key
-#   workspace_id      = var.ory_workspace_id
-#
-#   # Custom API URLs (defaults shown)
-#   console_api_url = "https://api.console.ory.sh"           # or set ORY_CONSOLE_API_URL env var
-#   project_api_url = "https://%s.projects.oryapis.com"      # or set ORY_PROJECT_API_URL env var
-# }
-
 variable "ory_workspace_api_key" {
   type        = string
   sensitive   = true
   description = "Ory Workspace API Key (ory_wak_...)"
 }
 
+variable "ory_workspace_id" {
+  type        = string
+  description = "Ory Workspace ID (UUID)"
+}
+
 variable "ory_project_api_key" {
   type        = string
   sensitive   = true
@@ -96,6 +94,47 @@ variable "ory_project_slug" {
 }
 ```
 
+Then create a `terraform.tfvars` file (do not commit this file):
+
+```hcl
+ory_workspace_api_key = "ory_wak_..."
+ory_workspace_id      = "..."
+ory_project_api_key   = "ory_pat_..."
+ory_project_id        = "..."
+ory_project_slug      = "..."
+```
+
+Alternatively, variables can be passed with `-var` parameter when running terraform commands:
+
+```bash
+terraform plan -var 'ory_workspace_api_key=ory_wak_...' -var 'ory_workspace_id=...' -var 'ory_project_api_key=ory_pat_...' -var 'ory_project_id=...' -var 'ory_project_slug=...'
+```
+
+Or use `TF_VAR_` environment variables:
+
+```bash
+export TF_VAR_ory_workspace_api_key="ory_wak_..."
+export TF_VAR_ory_workspace_id="..."
+export TF_VAR_ory_project_api_key="ory_pat_..."
+export TF_VAR_ory_project_id="..."
+export TF_VAR_ory_project_slug="..."
+
+terraform plan
+```
+
+## Which Credentials Do You Need?
+
+| Resource | Required Credentials |
+|----------|---------------------|
+| `ory_project`, `ory_workspace` | `workspace_api_key`, `workspace_id` |
+| `ory_organization` | `workspace_api_key`, `project_id` |
+| `ory_project_config`, `ory_action`, `ory_social_provider`, `ory_email_template` | `workspace_api_key`, `project_id` |
+| `ory_identity`, `ory_oauth2_client`, `ory_relationship` | `project_api_key`, `project_slug` |
+
+## Import Requirements
+
+When importing existing resources, ensure you have the appropriate credentials configured **before** running `terraform import`.
+
 <!-- schema generated by tfplugindocs -->
 ## Schema
 

docs/resources/action.md

@@ -1,5 +1,4 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "ory_action Resource - ory"
 subcategory: ""
 description: |-
@@ -10,6 +9,8 @@ description: |-
 
 Manages an Ory Action (webhook) for identity flows.
 
+Actions allow you to trigger webhooks at specific points in identity flows (login, registration, recovery, settings, verification).
+
 ## Example Usage
 
 ```terraform
@@ -58,6 +59,83 @@ resource "ory_action" "sync_verified" {
 }
 ```
 
+## Authentication Methods
+
+The `auth_method` attribute specifies which authentication method triggers the webhook. This is only used for `timing = "after"` webhooks.
+
+| Value | Description |
+|-------|-------------|
+| `password` | Password-based authentication (default) |
+| `oidc` | Social/OIDC authentication (Google, GitHub, etc.) |
+| `code` | One-time code (magic link, OTP) |
+| `webauthn` | Hardware security keys |
+| `passkey` | Passkey authentication |
+| `totp` | Time-based one-time password |
+| `lookup_secret` | Recovery/backup codes |
+
+~> **Note:** `auth_method` is only used for `timing = "after"` webhooks. For `timing = "before"` hooks, the webhook runs before any authentication method is invoked.
+
+## HTTP Method
+
+The `method` attribute specifies the HTTP method used when calling the webhook:
+
+| Value | Description |
+|-------|-------------|
+| `POST` | HTTP POST request (default) |
+| `GET` | HTTP GET request |
+| `PUT` | HTTP PUT request |
+| `PATCH` | HTTP PATCH request |
+| `DELETE` | HTTP DELETE request |
+
+## Import
+
+Actions must be imported with the HTTP method included in the import ID.
+
+**For "after" timing (post-hooks):**
+```shell
+terraform import ory_action.example "project_id:flow:after:auth_method:method:url"
+```
+
+**For "before" timing (pre-hooks):**
+```shell
+terraform import ory_action.example "project_id:flow:before:method:url"
+```
+
+### Examples
+
+```shell
+# Import a POST webhook for post-registration password flow
+terraform import ory_action.welcome \
+  "550e8400-e29b-41d4-a716-446655440000:registration:after:password:POST:https://api.example.com/webhooks/welcome"
+
+# Import a PATCH webhook for post-login social (OIDC) flow
+terraform import ory_action.social_login \
+  "550e8400-e29b-41d4-a716-446655440000:login:after:oidc:PATCH:https://api.example.com/webhooks/social"
+
+# Import a POST pre-login validation webhook
+terraform import ory_action.validate \
+  "550e8400-e29b-41d4-a716-446655440000:login:before:POST:https://api.example.com/webhooks/validate"
+```
+
+### Finding Import Values from Ory Console
+
+1. **project_id**: Settings → General → Project ID
+2. **flow**: The flow type (login, registration, recovery, settings, verification)
+3. **timing**: "before" or "after"
+4. **auth_method** (for "after" only): password, oidc, code, webauthn, passkey, totp, lookup_secret
+5. **method**: The HTTP method (POST, GET, PUT, PATCH, DELETE)
+6. **url**: The exact webhook URL - must match exactly including protocol and trailing slashes
+
+### Troubleshooting Import Errors
+
+If you see "Cannot import non-existent remote object", the import will show a warning listing webhooks found at that location. This helps you find the correct URL, method, and auth_method.
+
+Common issues:
+- **URL mismatch**: URLs must match exactly, including `https://` and any trailing `/`
+- **Wrong method**: Check the HTTP method configured for the webhook (POST, PATCH, etc.)
+- **Wrong auth_method**: Check which authentication method the webhook is configured for
+- **Wrong timing**: Check if the webhook is a pre-hook (before) or post-hook (after)
+
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
@@ -69,7 +147,7 @@ resource "ory_action" "sync_verified" {
 
 ### Optional
 
-- `auth_method` (String) Authentication method to hook into (password, oidc, code, webauthn, passkey, totp, lookup_secret). Required for 'after' timing.
+- `auth_method` (String) Authentication method that triggers the webhook. In the Ory Console UI, this is the "Method" selector. Valid values: `password` (default), `oidc` (social login), `code` (magic link/OTP), `webauthn`, `passkey`, `totp`, `lookup_secret`. Only used for `timing = "after"` webhooks.
 - `body` (String) Jsonnet template for the request body.
 - `can_interrupt` (Boolean) Allow webhook to interrupt/block the flow (default: false).
 - `method` (String) HTTP method (default: POST).

docs/resources/email_template.md

@@ -1,5 +1,4 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "ory_email_template Resource - ory"
 subcategory: ""
 description: |-
@@ -10,6 +9,25 @@ description: |-
 
 Manages an Ory Network email template.
 
+## Template Types
+
+| Template Type | UI Name | Description |
+|---------------|---------|-------------|
+| `registration_code_valid` | Registration via Code | Sent when user registers with a valid code |
+| `registration_code_invalid` | - | Sent when registration code is invalid/expired |
+| `login_code_valid` | Login via Code | Sent when user logs in with a valid code |
+| `login_code_invalid` | - | Sent when login code is invalid/expired |
+| `verification_code_valid` | Verification via Code (Valid) | Sent for email verification with valid code |
+| `verification_code_invalid` | - | Sent when verification code is invalid/expired |
+| `recovery_code_valid` | Recovery via Code (Valid) | Sent for account recovery with valid code |
+| `recovery_code_invalid` | - | Sent when recovery code is invalid/expired |
+| `verification_valid` | - | Legacy verification email (link-based) |
+| `verification_invalid` | - | Legacy verification invalid |
+| `recovery_valid` | - | Legacy recovery email (link-based) |
+| `recovery_invalid` | - | Legacy recovery invalid |
+
+**Note:** The "_invalid" templates are sent when a code has expired or is incorrect. The non-code variants (recovery_valid, verification_valid) are for legacy link-based flows.
+
 ## Example Usage
 
 ```terraform
@@ -105,14 +123,20 @@ resource "ory_email_template" "login_code" {
 }
 ```
 
+## Import
+
+```shell
+terraform import ory_email_template.welcome registration_code_valid
+```
+
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
 - `body_html` (String) HTML body template (Go template syntax).
 - `body_plaintext` (String) Plaintext body template (Go template syntax).
-- `template_type` (String) Template type (e.g., recovery_code_valid, verification_valid).
+- `template_type` (String) The email template type. See the Template Types table above for valid values and their UI equivalents. Common values: `registration_code_valid`, `login_code_valid`, `verification_code_valid`, `recovery_code_valid`.
 
 ### Optional