Skip to content

Commit 2f9a854

Browse files
sionsmithsionsmith
authored
Merge pull request #26 from osodevops/feat/environment-roles-25
feat: add WorkOS environment role support
2 parents 0f34cda + 068d22b commit 2f9a854

15 files changed

Lines changed: 1594 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

8+
## [Unreleased]
9+
10+
### Features
11+
12+
* add environment role resource and data source for WorkOS Authorization roles
13+
814
## [2.3.1](https://github.com/osodevops/terraform-provider-workos/compare/v2.3.0...v2.3.1) (2026-06-04)
915

1016

‎README.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,17 @@ resource "workos_organization_membership" "admin" {
9393
### Managing Roles
9494

9595
```hcl
96+
resource "workos_environment_role" "billing_admin" {
97+
slug = "billing-admin"
98+
name = "Billing Admin"
99+
description = "Can manage billing across organizations"
100+
101+
permissions = [
102+
workos_permission.billing_read.slug,
103+
workos_permission.billing_write.slug,
104+
]
105+
}
106+
96107
resource "workos_organization_role" "billing_admin" {
97108
organization_id = workos_organization.example.id
98109
slug = "org-billing-admin"
@@ -173,19 +184,39 @@ data "workos_organization_role" "billing" {
173184
slug = "org-billing-admin"
174185
}
175186
187+
# Look up environment role by slug
188+
data "workos_environment_role" "admin" {
189+
slug = "admin"
190+
}
191+
176192
# Look up permission by slug
177193
data "workos_permission" "billing_read" {
178194
slug = "billing:read"
179195
}
180196
```
181197

198+
### Importing Existing Resources
199+
200+
The provider does not automatically discover and adopt existing WorkOS objects. Import existing resources into Terraform or OpenTofu state before managing them in configuration.
201+
202+
```bash
203+
terraform import workos_organization.example org_01HXYZ...
204+
terraform import workos_permission.billing_read billing:read
205+
terraform import workos_environment_role.admin admin
206+
terraform import workos_organization_role.billing_admin org_01HXYZ.../org-billing-admin
207+
terraform import workos_organization_role_permission.billing_admin_read org_01HXYZ.../org-billing-admin/billing:read
208+
```
209+
210+
OpenTofu uses the same import IDs with `tofu import`.
211+
182212
## Resources
183213

184214
| Resource | Description |
185215
|----------|-------------|
186216
| `workos_organization` | Manages WorkOS organizations |
187217
| `workos_user` | Manages AuthKit users |
188218
| `workos_organization_membership` | Manages user-organization memberships |
219+
| `workos_environment_role` | Manages environment-level authorization roles |
189220
| `workos_organization_role` | Manages organization authorization roles |
190221
| `workos_permission` | Manages environment-level permissions |
191222
| `workos_organization_role_permission` | Assigns a permission to an organization role |
@@ -200,6 +231,7 @@ data "workos_permission" "billing_read" {
200231
| `workos_directory_user` | Retrieves directory-synced user |
201232
| `workos_directory_group` | Retrieves directory-synced group |
202233
| `workos_user` | Retrieves AuthKit user by ID, email, or external ID |
234+
| `workos_environment_role` | Retrieves environment-level role by slug or ID |
203235
| `workos_organization_role` | Retrieves organization role by slug or ID |
204236
| `workos_permission` | Retrieves permission by slug |
205237

‎docs/data-sources/environment_role.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
# generated by https://github.com/hashicorp/terraform-plugin-docs
3+
page_title: "workos_environment_role Data Source - workos"
4+
subcategory: ""
5+
description: |-
6+
Use this data source to get information about a WorkOS environment-level role.
7+
You can look up a role by its slug or ID.
8+
Example Usage
9+
By Slug
10+
11+
data "workos_environment_role" "admin" {
12+
slug = "admin"
13+
}
14+
15+
By ID
16+
17+
data "workos_environment_role" "example" {
18+
id = "role_01HXYZ..."
19+
}
20+
---
21+
22+
# workos_environment_role (Data Source)
23+
24+
Use this data source to get information about a WorkOS environment-level role.
25+
26+
You can look up a role by its slug or ID.
27+
28+
## Example Usage
29+
30+
### By Slug
31+
32+
```hcl
33+
data "workos_environment_role" "admin" {
34+
slug = "admin"
35+
}
36+
```
37+
38+
### By ID
39+
40+
```hcl
41+
data "workos_environment_role" "example" {
42+
id = "role_01HXYZ..."
43+
}
44+
```
45+
46+
## Example Usage
47+
48+
```terraform
49+
# Look up an environment-level role by slug
50+
data "workos_environment_role" "admin" {
51+
slug = "admin"
52+
}
53+
54+
output "admin_role_id" {
55+
value = data.workos_environment_role.admin.id
56+
}
57+
58+
output "admin_role_permissions" {
59+
value = data.workos_environment_role.admin.permissions
60+
}
61+
62+
# Look up an environment-level role by ID
63+
data "workos_environment_role" "by_id" {
64+
id = "role_01HXYZ..."
65+
}
66+
```
67+
68+
<!-- schema generated by tfplugindocs -->
69+
## Schema
70+
71+
### Optional
72+
73+
- `id` (String) The unique identifier of the environment role to look up.
74+
- `slug` (String) The slug identifier of the role to look up.
75+
76+
### Read-Only
77+
78+
- `created_at` (String) The timestamp when the role was created (RFC3339 format).
79+
- `description` (String) A description of the role.
80+
- `name` (String) The display name of the role.
81+
- `permissions` (Set of String) The permissions associated with the role.
82+
- `resource_type_slug` (String) The resource type slug this role is scoped to.
83+
- `type` (String) The type of the role.
84+
- `updated_at` (String) The timestamp when the role was last updated (RFC3339 format).

‎docs/resources/environment_role.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
# generated by https://github.com/hashicorp/terraform-plugin-docs
3+
page_title: "workos_environment_role Resource - workos"
4+
subcategory: ""
5+
description: |-
6+
Manages a WorkOS environment-level role.
7+
Environment roles are global to a WorkOS environment and can be assigned across
8+
organizations. They are identified by an immutable slug.
9+
The WorkOS public API does not currently expose environment-role deletion. Terraform
10+
can create, import, read, and update environment roles, but destroying this resource
11+
returns a diagnostic instead of silently leaving the role behind. Use terraform state rm
12+
or tofu state rm if you need Terraform to stop managing an existing role.
13+
When permissions is configured, the provider manages the complete permission set for
14+
the role by using WorkOS' replace-all permissions endpoint.
15+
Example Usage
16+
17+
resource "workos_environment_role" "billing_admin" {
18+
slug = "billing-admin"
19+
name = "Billing Admin"
20+
description = "Can manage billing across organizations"
21+
22+
permissions = [
23+
workos_permission.billing_read.slug,
24+
workos_permission.billing_write.slug,
25+
]
26+
}
27+
28+
Import
29+
Environment roles can be imported using their slug:
30+
31+
terraform import workos_environment_role.example billing-admin
32+
33+
OpenTofu uses the same import ID format:
34+
35+
tofu import workos_environment_role.example billing-admin
36+
---
37+
38+
# workos_environment_role (Resource)
39+
40+
Manages a WorkOS environment-level role.
41+
42+
Environment roles are global to a WorkOS environment and can be assigned across
43+
organizations. They are identified by an immutable slug.
44+
45+
The WorkOS public API does not currently expose environment-role deletion. Terraform
46+
can create, import, read, and update environment roles, but destroying this resource
47+
returns a diagnostic instead of silently leaving the role behind. Use `terraform state rm`
48+
or `tofu state rm` if you need Terraform to stop managing an existing role.
49+
50+
When `permissions` is configured, the provider manages the complete permission set for
51+
the role by using WorkOS' replace-all permissions endpoint.
52+
53+
## Example Usage
54+
55+
```hcl
56+
resource "workos_environment_role" "billing_admin" {
57+
slug = "billing-admin"
58+
name = "Billing Admin"
59+
description = "Can manage billing across organizations"
60+
61+
permissions = [
62+
workos_permission.billing_read.slug,
63+
workos_permission.billing_write.slug,
64+
]
65+
}
66+
```
67+
68+
## Import
69+
70+
Environment roles can be imported using their slug:
71+
72+
```shell
73+
terraform import workos_environment_role.example billing-admin
74+
```
75+
76+
OpenTofu uses the same import ID format:
77+
78+
```shell
79+
tofu import workos_environment_role.example billing-admin
80+
```
81+
82+
## Example Usage
83+
84+
```terraform
85+
# Manage an environment-level role
86+
resource "workos_environment_role" "billing_admin" {
87+
slug = "billing-admin"
88+
name = "Billing Admin"
89+
description = "Can manage billing across organizations"
90+
91+
permissions = [
92+
workos_permission.billing_read.slug,
93+
workos_permission.billing_write.slug,
94+
]
95+
}
96+
97+
resource "workos_permission" "billing_read" {
98+
slug = "billing:read"
99+
name = "Read Billing"
100+
}
101+
102+
resource "workos_permission" "billing_write" {
103+
slug = "billing:write"
104+
name = "Write Billing"
105+
}
106+
107+
output "billing_admin_role_id" {
108+
value = workos_environment_role.billing_admin.id
109+
}
110+
```
111+
112+
<!-- schema generated by tfplugindocs -->
113+
## Schema
114+
115+
### Required
116+
117+
- `name` (String) The display name of the role.
118+
- `slug` (String) The slug identifier for the role. Must be unique within the environment. Changing this value after creation is not supported because WorkOS does not currently expose a public delete API for environment roles.
119+
120+
### Optional
121+
122+
- `description` (String) A description of the role.
123+
- `permissions` (Set of String) The complete set of permissions associated with the role. When configured, this set is authoritative.
124+
- `resource_type_slug` (String) The resource type slug this role is scoped to. Changing this value after creation is not supported because WorkOS does not currently expose a public delete API for environment roles.
125+
126+
### Read-Only
127+
128+
- `created_at` (String) The timestamp when the role was created (RFC3339 format).
129+
- `id` (String) The unique identifier of the environment role.
130+
- `type` (String) The type of the role.
131+
- `updated_at` (String) The timestamp when the role was last updated (RFC3339 format).

‎examples/data-sources/workos_environment_role/data-source.tf‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Look up an environment-level role by slug
2+
data "workos_environment_role" "admin" {
3+
slug = "admin"
4+
}
5+
6+
output "admin_role_id" {
7+
value = data.workos_environment_role.admin.id
8+
}
9+
10+
output "admin_role_permissions" {
11+
value = data.workos_environment_role.admin.permissions
12+
}
13+
14+
# Look up an environment-level role by ID
15+
data "workos_environment_role" "by_id" {
16+
id = "role_01HXYZ..."
17+
}

‎examples/resources/workos_environment_role/resource.tf‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Manage an environment-level role
2+
resource "workos_environment_role" "billing_admin" {
3+
slug = "billing-admin"
4+
name = "Billing Admin"
5+
description = "Can manage billing across organizations"
6+
7+
permissions = [
8+
workos_permission.billing_read.slug,
9+
workos_permission.billing_write.slug,
10+
]
11+
}
12+
13+
resource "workos_permission" "billing_read" {
14+
slug = "billing:read"
15+
name = "Read Billing"
16+
}
17+
18+
resource "workos_permission" "billing_write" {
19+
slug = "billing:write"
20+
name = "Write Billing"
21+
}
22+
23+
output "billing_admin_role_id" {
24+
value = workos_environment_role.billing_admin.id
25+
}

0 commit comments

Comments
 (0)