Terraform import failing with 404 for existing Architect flow via CX as Code

General Discussion
1

Context:

I am attempting to bring an existing Genesys Cloud Architect flow under Terraform management using the CX as Code provider. I have identified the flowId from the UI and am trying to import the resource into my local state file. The documentation suggests using the terraform import command with the resource address and the ID. However, I am consistently encountering a 404 Not Found error during the import phase, despite the flow existing and being accessible via the Genesys Cloud UI and direct API calls.

Here is the Terraform resource definition I am using:

resource "genesyscloud_architect_flow" "customer_service_flow" {
 name = "Customer Service Flow - Updated"
 description = "Main inbound customer service flow"
 enabled = true
 version = 1
 
 # ... other configuration blocks omitted for brevity ...
}

I execute the following command:

terraform import genesyscloud_architect_flow.customer_service_flow <actual-flow-id-from-ui>

The error output is:

╷
│ Error: Resource not found
│ 
│ with genesyscloud_architect_flow.customer_service_flow,
│ on main.tf line 1, in resource "genesyscloud_architect_flow" "customer_service_flow":
│ 1: resource "genesyscloud_architect_flow" "customer_service_flow" {
│ 
│ The specified resource could not be found. Please ensure the ID is correct and you have permissions to access it.
╵

I have verified that the machine user associated with the Terraform configuration has the Architect:Flow:Read permission. I can successfully retrieve the flow details using the /api/v2/architect/flows/<flow-id> endpoint with the same credentials. The flow is not in a ‘deleted’ state. Is there a specific format required for the ID, or does the CX as Code provider require a different identifier than the standard UUID for import operations? I have also tried using the genesys cloud architect flow import CLI command to generate the config, but I need to sync the state, not just the config.

Question:

What is the correct procedure to import an existing Architect flow into Terraform state when the standard terraform import command returns a 404 error for a valid flow ID? Are there known issues with the CX as Code provider regarding flow imports, or am I missing a specific flag or permission scope required for the import action specifically?

2

The 404 error during terraform import for Architect flows is rarely a network issue. It is usually caused by the ID format mismatch between the UI display and the API expectation. The CX as Code provider expects the raw UUID without any prefixing or suffixing that might appear in browser URLs.

First, verify the exact ID. Do not copy from the browser address bar if it contains fragments like #/architect/flows/.... Instead, use the API to retrieve the canonical ID:

curl -X GET "https://api.mypurecloud.com/api/v2/architect/flows?name=YourFlowName&pageSize=1" \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Accept: application/json" | jq '.entities[0].id'

Ensure the ID returned by the API matches exactly what you pass to Terraform. The import command must look like this:

terraform import module.architect.genesyscloud_architect_flow.inbound_flow <exact_uuid_from_api>

If the flow is a draft or has been deleted in the UI but remains in the trash, the API will return a 404. Check the flow status via /api/v2/architect/flows/{flowId}. If the status is draft, ensure your Terraform configuration does not attempt to set enabled to true immediately if the flow is not fully published.

Also, check for naming conflicts. If multiple flows share the same name, the provider might struggle to resolve the resource during import if you are using name-based lookups elsewhere in your code. Stick to UUIDs for imports.

Here is a minimal configuration block to verify your state after import:

resource "genesyscloud_architect_flow" "inbound_flow" {
 name = "Inbound Message Handler"
 description = "Handles inbound web messages"
 type = "INBOUND_MESSAGE"
 enabled = true
 
 # Ensure no conflicting attributes exist
 flow_metadata {
 # Add any required metadata here
 }
}

Reference the import troubleshooting guide here: https://support.genesys.com/s/article/Terraform-Import-404-Troubleshooting

3

have you tried verifying the token scopes before running the import command? the suggestion above regarding the uuid format is technically correct, but you are ignoring the authentication context. the docs state: “The CX as Code provider requires read access to the specific resource type.” if your service account lacks architect:flow:read, the api returns 404 instead of 403 to hide existence.

i debug this by testing the endpoint directly in python first. if this fails, terraform will fail.

import requests
url = "https://api.mypurecloud.com/api/v2/architect/flows/<YOUR_UUID>"
headers = {
 "Authorization": "Bearer <YOUR_TOKEN>",
 "Content-Type": "application/json"
}
r = requests.get(url, headers=headers)
print(r.status_code, r.text)

if this returns 404, your scope is wrong or the flow is archived. check the service account permissions in admin. do not trust the ui export if the underlying api call is blocked.

4

To fix this easily, this is to validate the token permissions using a direct API call before running the terraform command. the suggestion above about architect:flow:read scope is correct, but in my react desktop builds, i see similar issues where the implicit grant flow drops specific scopes during refresh. you must ensure the service account token actually contains the required scopes.

  1. extract the bearer token from your terraform provider configuration.
  2. use curl to verify access to the specific flow endpoint.
  3. check the HTTP status code. a 403 means scope issue. a 404 means wrong ID or org mismatch.

here is the curl command to test your token against the flow ID:

curl -X GET "https://api.mypurecloud.com/api/v2/architect/flows/{flowId}" \
 -H "Authorization: Bearer {your_token}" \
 -H "Accept: application/json"

if the curl command returns 404, the ID is incorrect or the flow is in a different org. if it returns 403, your service account lacks architect:flow:read. in my react desktop builds, i often encounter this when the OAuth implicit grant with PKCE fails to persist the full scope list. ensure your service account has the architect:flow:read and architect:flow:write scopes assigned.

also, check the org ID. sometimes the API returns 404 if the token is for a different org than the flow exists in. verify the org ID in the token payload matches the flow’s org ID. this is a common gotcha in multi-org environments.

for more details on scope validation, see this support article: https://support.genesys.cloud/faq/oauth-scope-validation-for-cxascode

fix the scope or ID issue, then retry the import. this should resolve the 404 error.

5

TL;DR: Verify the token scope via C# first.

Ah, this is a known issue… The documentation states “the CX as Code provider requires read access to the specific resource type.” If your service account lacks architect:flow:read, the API returns 404. I usually test the endpoint directly in .NET before importing.

var flows = await platformClient.Architect.FlowsApi.GetFlowsAsync();