https://github.com/osodevops/terraform-provider-workos
Terraform provider for WorkOS - manage organizations, SSO connections, directory sync, webhooks, users, and AuthKit resources
https://github.com/osodevops/terraform-provider-workos
authentication authkit directory-sync golang identity infrastructure-as-code sso terraform terraform-provider workos
Last synced: about 23 hours ago
JSON representation
Terraform provider for WorkOS - manage organizations, SSO connections, directory sync, webhooks, users, and AuthKit resources
- Host: GitHub
- URL: https://github.com/osodevops/terraform-provider-workos
- Owner: osodevops
- License: mpl-2.0
- Created: 2026-01-31T11:46:00.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-03-25T12:55:55.000Z (11 days ago)
- Last Synced: 2026-03-26T15:56:54.724Z (9 days ago)
- Topics: authentication, authkit, directory-sync, golang, identity, infrastructure-as-code, sso, terraform, terraform-provider, workos
- Language: Go
- Homepage: https://registry.terraform.io/providers/osodevops/workos/latest
- Size: 241 KB
- Stars: 2
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# WorkOS Terraform Provider
Terraform provider for managing [WorkOS](https://workos.com) resources including organizations, users, organization memberships, roles, and permissions.
## Requirements
- [Terraform](https://www.terraform.io/downloads.html) >= 1.0
- [Go](https://golang.org/doc/install) >= 1.21 (for development)
## Installation
### From Terraform Registry (Recommended)
```hcl
terraform {
required_providers {
workos = {
source = "osodevops/workos"
version = "~> 1.0"
}
}
}
provider "workos" {
api_key = var.workos_api_key
}
```
### Local Development
```bash
# Clone the repository
git clone https://github.com/osodevops/terraform-provider-workos.git
cd terraform-provider-workos
# Build the provider
make build
# Install locally
make install
```
## Usage
### Provider Configuration
```hcl
provider "workos" {
api_key = var.workos_api_key # Or set WORKOS_API_KEY env var
client_id = var.workos_client_id # Or set WORKOS_CLIENT_ID env var (optional)
base_url = "https://api.workos.com" # Optional, defaults to production API
}
```
### Managing Organizations
```hcl
resource "workos_organization" "example" {
name = "Acme Corporation"
external_id = "acme-corp-123"
domains = ["acme.com", "acmecorp.com"]
metadata = {
tier = "enterprise"
region = "us-east-1"
}
}
```
### Managing Users
```hcl
resource "workos_user" "admin" {
email = "admin@example.com"
first_name = "Admin"
last_name = "User"
external_id = "admin-001"
email_verified = true
metadata = {
department = "Engineering"
title = "Platform Lead"
}
}
resource "workos_organization_membership" "admin" {
user_id = workos_user.admin.id
organization_id = workos_organization.example.id
role_slug = "admin"
}
```
### Managing Roles
```hcl
resource "workos_organization_role" "billing_admin" {
organization_id = workos_organization.example.id
slug = "org-billing-admin"
name = "Billing Admin"
description = "Can manage billing and invoices"
}
resource "workos_organization_role" "viewer" {
organization_id = workos_organization.example.id
slug = "org-viewer"
name = "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
# Look up organization by ID
data "workos_organization" "by_id" {
id = "org_01HXYZ..."
}
# Look up organization by domain
data "workos_organization" "by_domain" {
domain = "acme.com"
}
# Look up organization by external ID
data "workos_organization" "by_external_id" {
external_id = "acme-corp-123"
}
# Look up user by email
data "workos_user" "john" {
email = "john@example.com"
}
# Look up user by external ID
data "workos_user" "by_ext" {
external_id = "admin-001"
}
# Look up organization role by slug
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
| Resource | Description |
|----------|-------------|
| `workos_organization` | Manages WorkOS organizations |
| `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
| Data Source | Description |
|-------------|-------------|
| `workos_organization` | Retrieves organization by ID, domain, or external ID |
| `workos_connection` | Retrieves SSO connection by ID or org/type (read-only) |
| `workos_directory` | Retrieves directory by ID or organization (read-only) |
| `workos_directory_user` | Retrieves directory-synced user |
| `workos_directory_group` | Retrieves directory-synced group |
| `workos_user` | Retrieves AuthKit user by ID, email, or external ID |
| `workos_organization_role` | Retrieves organization role by slug or ID |
| `workos_permission` | Retrieves permission by slug |
## Development
### Building
```bash
make build
```
### Testing
```bash
# Unit tests
make test
# Acceptance tests (requires WorkOS API credentials)
export WORKOS_API_KEY="sk_test_..."
export WORKOS_CLIENT_ID="client_..."
make testacc
```
### Generating Documentation
```bash
make docs
```
### Linting
```bash
make lint
```
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/my-feature`)
3. Commit your changes (`git commit -am 'Add new feature'`)
4. Push to the branch (`git push origin feature/my-feature`)
5. Open a Pull Request
### Commit Message Format
```
feat(resource): add new attribute support
fix(organization): handle domain validation
docs(readme): update installation instructions
test(connection): add acceptance tests
```
## License
MPL-2.0 - See [LICENSE](LICENSE) for details.
## Support
- [Documentation](https://registry.terraform.io/providers/osodevops/workos/latest/docs)
- [GitHub Issues](https://github.com/osodevops/terraform-provider-workos/issues)
- [WorkOS Documentation](https://workos.com/docs)