# keenauth_role

The `keenauth_role` resource manages a role of the environment and its complete permission set. A role that belongs to one organization is a different resource, `keenauth_organization_role`. The `keenauth_role` data source reads a role by `id` or `key`.

```terraform
resource "keenauth_permission" "invoices_read" {
  api_id = "api_01j9zq3v8c5m2x7k4t6r1n0b3d"
  value  = "invoices:read"
}

resource "keenauth_role" "billing" {
  key         = "billing"
  name        = "Billing"
  description = "Invoices and payment methods."

  permission_ids = [keenauth_permission.invoices_read.id]
}

data "keenauth_role" "billing" {
  key = "billing"
}
```

## Lifecycle

- `key` is unique in the environment, appears in the `org_roles` claim and cannot be changed: a new key replaces the role.
- `name` has 1 to 128 characters and `description` at most 1024. Neither may start or end with whitespace, because the API trims them.
- `permission_ids` is the complete set (at most 500). It is written with a separate request after the role fields; if that request fails on create, the role stays in state as tainted and is replaced on the next apply. A permission added or removed elsewhere is reverted by the next apply.
- `is_privileged` marks a privileged role. In self-service only an administrator who holds the organization admin role can assign it, and an external group mapping to it needs `roles:write` and an approval. Making an existing role privileged leaves its group mappings unapproved until they are approved. The default is `false`; when you import a privileged role, write `is_privileged = true` explicitly, otherwise the next apply makes the role non-privileged.
- Updates and deletes send `If-Match` with the last read ETag. If the role changed after the plan was made, the API answers `412` and nothing changes; run `plan` again.
- With `force_destroy = true` an assigned role is deleted too and its assignments are removed in the same request; otherwise deleting an assigned role fails with `409 role_in_use`. A role used as an organization's admin or default member role cannot be deleted at all. Changing only `force_destroy` sends no request.
- Assignments of roles to users and memberships are not resources. They are personal data and never go into state; manage them with the API, the CLI or the dashboard.

## Import

Import by key or by ID:

```shell
tofu import keenauth_role.billing billing
tofu import keenauth_role.billing rol_01j9zq3v8c5m2x7k4t6r1n0b3d
```