feat: add permission resource, data source, and organization role permission resource

README.md

@@ -1,6 +1,6 @@
 # WorkOS Terraform Provider
 
-Terraform provider for managing [WorkOS](https://workos.com) resources including organizations, users, organization memberships, and roles.
+Terraform provider for managing [WorkOS](https://workos.com) resources including organizations, users, organization memberships, roles, and permissions.
 
 ## Requirements
 
@@ -95,6 +95,38 @@ resource "workos_organization_role" "viewer" {
 }
 ```
 
+### Managing Permissions
+
+```hcl
+resource "workos_permission" "billing_read" {
+  slug        = "billing:read"
+  name        = "Read Billing"
+  description = "Allows reading billing data"
+}
+
+resource "workos_permission" "billing_write" {
+  slug        = "billing:write"
+  name        = "Write Billing"
+  description = "Allows modifying billing data"
+}
+```
+
+### Assigning Permissions to Organization Roles
+
+```hcl
+resource "workos_organization_role_permission" "billing_admin_read" {
+  organization_id = workos_organization.example.id
+  role_slug       = workos_organization_role.billing_admin.slug
+  permission      = workos_permission.billing_read.slug
+}
+
+resource "workos_organization_role_permission" "billing_admin_write" {
+  organization_id = workos_organization.example.id
+  role_slug       = workos_organization_role.billing_admin.slug
+  permission      = workos_permission.billing_write.slug
+}
+```
+
 ### Data Sources
 
 ```hcl
@@ -118,6 +150,11 @@ data "workos_organization_role" "billing" {
   organization_id = workos_organization.example.id
   slug            = "org-billing-admin"
 }
+
+# Look up permission by slug
+data "workos_permission" "billing_read" {
+  slug = "billing:read"
+}
 ```
 
 ## Resources
@@ -128,6 +165,8 @@ data "workos_organization_role" "billing" {
 | `workos_user` | Manages AuthKit users |
 | `workos_organization_membership` | Manages user-organization memberships |
 | `workos_organization_role` | Manages organization authorization roles |
+| `workos_permission` | Manages environment-level permissions |
+| `workos_organization_role_permission` | Assigns a permission to an organization role |
 
 ## Data Sources
 
@@ -140,6 +179,7 @@ data "workos_organization_role" "billing" {
 | `workos_directory_group` | Retrieves directory-synced group |
 | `workos_user` | Retrieves AuthKit user by ID or email |
 | `workos_organization_role` | Retrieves organization role by slug or ID |
+| `workos_permission` | Retrieves permission by slug |
 
 ## Development
 

docs/data-sources/permission.md

@@ -0,0 +1,52 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "workos_permission Data Source - workos"
+subcategory: ""
+description: |-
+  Use this data source to get information about a WorkOS Permission.
+  You can look up a permission by its slug.
+  Example Usage
+
+  data "workos_permission" "billing_read" {
+    slug = "billing:read"
+  }
+---
+
+# workos_permission (Data Source)
+
+Use this data source to get information about a WorkOS Permission.
+
+You can look up a permission by its slug.
+
+## Example Usage
+
+```hcl
+data "workos_permission" "billing_read" {
+  slug = "billing:read"
+}
+```
+
+## Example Usage
+
+```terraform
+data "workos_permission" "billing_read" {
+  slug = "billing:read"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `slug` (String) The slug identifier of the permission to look up.
+
+### Read-Only
+
+- `created_at` (String) The timestamp when the permission was created (RFC3339 format).
+- `description` (String) A description of the permission.
+- `id` (String) The unique identifier of the permission.
+- `name` (String) The display name of the permission.
+- `resource_type_slug` (String) The slug of the resource type this permission applies to.
+- `system` (Boolean) Whether this is a system-managed permission.
+- `updated_at` (String) The timestamp when the permission was last updated (RFC3339 format).

docs/resources/organization_role_permission.md

@@ -0,0 +1,69 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "workos_organization_role_permission Resource - workos"
+subcategory: ""
+description: |-
+  Assigns a permission to a WorkOS Organization Role.
+  This resource manages the assignment of a permission to an organization role. All fields
+  are immutable — changing any field will destroy and recreate the assignment.
+  Example Usage
+
+  resource "workos_organization_role_permission" "assign" {
+    organization_id = workos_organization.acme.id
+    role_slug       = workos_organization_role.billing.slug
+    permission      = workos_permission.billing_read.slug
+  }
+
+  Import
+  Organization role permissions can be imported using a composite key of organization ID, role slug, and permission slug:
+
+  terraform import workos_organization_role_permission.example org_01HXYZ.../billing-admin/billing:read
+---
+
+# workos_organization_role_permission (Resource)
+
+Assigns a permission to a WorkOS Organization Role.
+
+This resource manages the assignment of a permission to an organization role. All fields
+are immutable — changing any field will destroy and recreate the assignment.
+
+## Example Usage
+
+```hcl
+resource "workos_organization_role_permission" "assign" {
+  organization_id = workos_organization.acme.id
+  role_slug       = workos_organization_role.billing.slug
+  permission      = workos_permission.billing_read.slug
+}
+```
+
+## Import
+
+Organization role permissions can be imported using a composite key of organization ID, role slug, and permission slug:
+
+```shell
+terraform import workos_organization_role_permission.example org_01HXYZ.../billing-admin/billing:read
+```
+
+## Example Usage
+
+```terraform
+resource "workos_organization_role_permission" "billing_admin_read" {
+  organization_id = workos_organization.example.id
+  role_slug       = workos_organization_role.billing_admin.slug
+  permission      = workos_permission.billing_read.slug
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `organization_id` (String) The ID of the organization the role belongs to (e.g., `org_01HXYZ...`).
+- `permission` (String) The slug of the permission to assign to the role.
+- `role_slug` (String) The slug of the organization role to assign the permission to.
+
+### Read-Only
+
+- `id` (String) The composite identifier of the organization role permission (`organization_id/role_slug/permission`).

docs/resources/permission.md

@@ -0,0 +1,76 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "workos_permission Resource - workos"
+subcategory: ""
+description: |-
+  Manages a WorkOS Permission.
+  Permissions are environment-level resources that can be assigned to both environment roles
+  and organization roles. Permissions are identified by their slug.
+  Example Usage
+
+  resource "workos_permission" "billing_read" {
+    slug        = "billing:read"
+    name        = "Read Billing"
+    description = "Allows reading billing data"
+  }
+
+  Import
+  Permissions can be imported using their slug:
+
+  terraform import workos_permission.example billing:read
+---
+
+# workos_permission (Resource)
+
+Manages a WorkOS Permission.
+
+Permissions are environment-level resources that can be assigned to both environment roles
+and organization roles. Permissions are identified by their slug.
+
+## Example Usage
+
+```hcl
+resource "workos_permission" "billing_read" {
+  slug        = "billing:read"
+  name        = "Read Billing"
+  description = "Allows reading billing data"
+}
+```
+
+## Import
+
+Permissions can be imported using their slug:
+
+```shell
+terraform import workos_permission.example billing:read
+```
+
+## Example Usage
+
+```terraform
+resource "workos_permission" "billing_read" {
+  slug        = "billing:read"
+  name        = "Read Billing"
+  description = "Allows reading billing data"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `name` (String) The display name of the permission.
+- `slug` (String) The slug identifier for the permission. Must be unique within the environment.
+
+### Optional
+
+- `description` (String) A description of the permission.
+- `resource_type_slug` (String) The slug of the resource type this permission applies to.
+
+### Read-Only
+
+- `created_at` (String) The timestamp when the permission was created (RFC3339 format).
+- `id` (String) The unique identifier of the permission.
+- `system` (Boolean) Whether this is a system-managed permission.
+- `updated_at` (String) The timestamp when the permission was last updated (RFC3339 format).

examples/data-sources/workos_permission/data-source.tf

@@ -0,0 +1,3 @@
+data "workos_permission" "billing_read" {
+  slug = "billing:read"
+}

examples/resources/workos_organization_role_permission/resource.tf

@@ -0,0 +1,5 @@
+resource "workos_organization_role_permission" "billing_admin_read" {
+  organization_id = workos_organization.example.id
+  role_slug       = workos_organization_role.billing_admin.slug
+  permission      = workos_permission.billing_read.slug
+}

examples/resources/workos_permission/resource.tf

@@ -0,0 +1,5 @@
+resource "workos_permission" "billing_read" {
+  slug        = "billing:read"
+  name        = "Read Billing"
+  description = "Allows reading billing data"
+}

internal/client/models.go

@@ -212,3 +212,41 @@ type OrganizationRoleListResponse struct {
 	Data         []OrganizationRole `json:"data"`
 	ListMetadata ListMetadata       `json:"list_metadata"`
 }
+
+// Permission represents a WorkOS Permission
+type Permission struct {
+	ID               string    `json:"id"`
+	Object           string    `json:"object"`
+	Slug             string    `json:"slug"`
+	Name             string    `json:"name"`
+	Description      string    `json:"description,omitempty"`
+	System           bool      `json:"system"`
+	ResourceTypeSlug string    `json:"resource_type_slug,omitempty"`
+	CreatedAt        time.Time `json:"created_at"`
+	UpdatedAt        time.Time `json:"updated_at"`
+}
+
+// PermissionCreateRequest represents the request to create a permission
+type PermissionCreateRequest struct {
+	Slug             string `json:"slug"`
+	Name             string `json:"name"`
+	Description      string `json:"description,omitempty"`
+	ResourceTypeSlug string `json:"resource_type_slug,omitempty"`
+}
+
+// PermissionUpdateRequest represents the request to update a permission
+type PermissionUpdateRequest struct {
+	Name        string `json:"name,omitempty"`
+	Description string `json:"description,omitempty"`
+}
+
+// PermissionListResponse represents the response from listing permissions
+type PermissionListResponse struct {
+	Data         []Permission `json:"data"`
+	ListMetadata ListMetadata `json:"list_metadata"`
+}
+
+// AddPermissionRequest represents the request to add a permission to a role
+type AddPermissionRequest struct {
+	Slug string `json:"slug"`
+}

internal/client/organization_role_permissions.go

@@ -0,0 +1,31 @@
+// Copyright (c) OSO DevOps
+// SPDX-License-Identifier: MPL-2.0
+
+package client
+
+import (
+	"context"
+	"fmt"
+)
+
+// AddOrganizationRolePermission adds a permission to an organization role
+func (c *Client) AddOrganizationRolePermission(ctx context.Context, orgID, roleSlug, permSlug string) (*OrganizationRole, error) {
+	req := &AddPermissionRequest{
+		Slug: permSlug,
+	}
+	var role OrganizationRole
+	err := c.Post(ctx, fmt.Sprintf("/authorization/organizations/%s/roles/%s/permissions", orgID, roleSlug), req, &role)
+	if err != nil {
+		return nil, fmt.Errorf("failed to add permission to organization role: %w", err)
+	}
+	return &role, nil
+}
+
+// RemoveOrganizationRolePermission removes a permission from an organization role
+func (c *Client) RemoveOrganizationRolePermission(ctx context.Context, orgID, roleSlug, permSlug string) error {
+	err := c.Delete(ctx, fmt.Sprintf("/authorization/organizations/%s/roles/%s/permissions/%s", orgID, roleSlug, permSlug))
+	if err != nil {
+		return fmt.Errorf("failed to remove permission from organization role: %w", err)
+	}
+	return nil
+}