# keenauth_permission

The `keenauth_permission` resource defines a permission (an OAuth scope) of an API, with the texts the consent screen shows. The provider does not manage the API itself: pass the ID of an existing API as `api_id`. Put the permission into a role with `keenauth_role`.

```terraform
resource "keenauth_permission" "invoices_read" {
  api_id       = "api_01j9zq3v8c5m2x7k4t6r1n0b3d"
  value        = "invoices:read"
  display_name = "Read invoices"
  description  = "See the invoices of the account."
  sensitivity  = "normal"

  consent_text_i18n = {
    de = "Rechnungen ansehen"
    tr = "Faturaları görüntüle"
  }
}
```

## Lifecycle

- `value` has the form `resource:action` and appears in the `permissions` claim of access tokens. It is unique in the API and cannot be changed: a new value replaces the permission. The `idp_` prefix belongs to the system API.
- `display_name`, `description` and the texts in `consent_text_i18n` are plain text: no control characters, no line or paragraph separators, no bidirectional override characters, and, for `display_name` and `description`, no leading or trailing whitespace (the API trims those two). A text in `consent_text_i18n` is stored as written, but it must not be blank. An empty text is not allowed; remove the attribute instead.
- `consent_text_i18n` is replaced as a whole map. The keys are language tags such as `de` or `pt-BR`; at most 30 languages. Remove the attribute to clear it.
- `sensitivity` is `normal` or `sensitive`; a sensitive permission is highlighted on the consent screen.
- A permission row has no version, so the API offers no `If-Match` check for it. The provider reads the API's permission list on every plan, shows any change made elsewhere as drift and sends only the changed fields.
- Removing the resource deletes the permission and removes it from every role and from application permission lists. The next refresh of those roles shows the change.
- The system API accepts no new permissions and its permissions cannot be deleted (`409 conflict`). An API holds at most 1,000 permissions.
- A permission deleted outside the provider is removed from state and planned again.

## Import

Import by API ID and permission ID, or by API ID and value:

```shell
tofu import keenauth_permission.invoices_read api_01j9zq3v8c5m2x7k4t6r1n0b3d/perm_01j9zq3v8c5m2x7k4t6r1n0b3e
tofu import keenauth_permission.invoices_read api_01j9zq3v8c5m2x7k4t6r1n0b3d/invoices:read
```