zitadel-terraform

Use the zitadel/zitadel Terraform provider to declare organizations, projects, applications, users, and policies as HCL resources. Configure the provider with a domain and one authentication method such as a personal access token or JWT profile file, then run terraform apply.

The provider supports personal access tokens, JWT profile files or inline JSON for service accounts, pre-signed JWT files, and a system_api block for instance-level operations. JWT profile is preferred for long-running automation since PATs expire.

Some ingress gateways such as Cilium Gateway return 403 for gRPC traffic even with GRPCRoute configured. The workaround is to bypass the gateway with kubectl port-forward, a hosts entry, and a PAT, then apply with insecure mode enabled.

zitadel_organization uses the org/v2 API and targets ZITADEL 4.x and later, while zitadel_org is the backward-compatible resource that auto-falls back across v3 and v4. Prefer zitadel_organization for new deployments on ZITADEL 4.x.

Instance-level resources like zitadel_system_features and zitadel_instance_* require System API authentication configured in the provider block. A PAT fails with AUTH-5mWD2 even for IAM_OWNER users, which is intentional by design.

Use terraform import with the format <id>[:<org_id>][:<additional_fields>], for example terraform import zitadel_project.example 'projectID:orgID'. Default policies are singletons and should be imported before managing them with Terraform.