docs: add LA note and update app users

docs/data-sources/organization_application_user.md

@@ -3,24 +3,36 @@
 page_title: "aiven_organization_application_user Data Source - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  Retrieves information about an organization application user from Aiven.
+  Gets information about an application user.
+  This data source is in the limited availability stage and may change without notice.  To enable this feature, contact the sales team mailto:[email protected]. After it's enabled, set
+  the PROVIDER_AIVEN_ENABLE_BETA environment variable to use the data source.
 ---
 
 # aiven_organization_application_user (Data Source)
 
-Retrieves information about an organization application user from Aiven.
+Gets information about an application user. 
 
+**This data source is in the limited availability stage and may change without notice.**  To enable this feature, contact the [sales team](mailto:[email protected]). After it's enabled, set
+the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to use the data source.
 
+## Example Usage
+
+```terraform
+data "aiven_organization_application_user" "tf_user" {
+  organization_id = aiven_organization.main.id
+  user_id = "u123a456b7890c"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
-- `organization_id` (String) Identifier of the organization the application user belongs to.
-- `user_id` (String) Identifier of the organization application user.
+- `organization_id` (String) The ID of the organization the application user belongs to.
+- `user_id` (String) The ID of the application user.
 
 ### Read-Only
 
-- `email` (String) Email of the organization application user.
-- `name` (String) Name of the organization application user.
+- `email` (String) The auto-generated email address of the application user.
+- `name` (String) Name of the application user.

docs/resources/organization_application_user.md

@@ -3,38 +3,45 @@
 page_title: "aiven_organization_application_user Resource - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  Creates and manages an organization application user. Application users can be used for programmatic access to the platform.
-  This resource is in the limited availability stage and may change without notice.
-  To enable this feature, contact the sales team mailto:[email protected]. After it's enabled, set
+  Creates and manages an organization application user. Application users https://aiven.io/docs/platform/howto/manage-application-users can be used for programmatic access to the platform.
+  This resource is in the limited availability stage and may change without notice.  To enable this feature, contact the sales team mailto:[email protected]. After it's enabled, set
   the PROVIDER_AIVEN_ENABLE_BETA environment variable to use the resource.
 ---
 
 # aiven_organization_application_user (Resource)
 
-Creates and manages an organization application user. Application users can be used for programmatic access to the platform. 
-**This resource is in the limited availability stage and may change without notice.** 
-To enable this feature, contact the [sales team](mailto:[email protected]). After it's enabled, set
+Creates and manages an organization application user. [Application users](https://aiven.io/docs/platform/howto/manage-application-users) can be used for programmatic access to the platform. 
+
+**This resource is in the limited availability stage and may change without notice.**  To enable this feature, contact the [sales team](mailto:[email protected]). After it's enabled, set
 the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to use the resource.
 
+## Example Usage
 
+```terraform
+resource "aiven_organization_application_user" "tf_user" {
+  organization_id = aiven_organization.main.id
+  name = "app-terraform"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
-- `name` (String) Name of the organization application user.
-- `organization_id` (String) Identifier of the organization the application user belongs to.
+- `name` (String) Name of the application user.
+- `organization_id` (String) The ID of the organization the application user belongs to.
 
 ### Optional
 
 - `timeouts` (Block, Optional) (see [below for nested schema](#nestedblock--timeouts))
 
 ### Read-Only
 
-- `email` (String) Email of the organization application user.
-- `id` (String) Compound identifier of the organization application user.
-- `user_id` (String) Identifier of the organization application user.
+- `email` (String) An email address automatically generated by Aiven to help identify the application user. 
+				No notifications are sent to this email.
+- `id` (String) A compound identifier of the resource in the format `organization_id/user_id`.
+- `user_id` (String) The ID of the application user.
 
 <a id="nestedblock--timeouts"></a>
 ### Nested Schema for `timeouts`
@@ -45,3 +52,11 @@ Optional:
 - `delete` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours). Setting a timeout for a Delete operation is only applicable if changes are saved into state before the destroy operation occurs.
 - `read` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours). Read operations occur during any refresh or planning operation when refresh is enabled.
 - `update` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours).
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+terraform import aiven_organization_application_user.example ORGANIZATION_ID/USER_ID
+```

docs/resources/organization_application_user_token.md

@@ -3,45 +3,59 @@
 page_title: "aiven_organization_application_user_token Resource - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  Creates and manages an organization application user token in Aiven.
+  Creates and manages an application user token. Review the best practices https://aiven.io/docs/platform/concepts/application-users#security-best-practices for securing application users and their tokens.
   This resource is in the beta stage and may change without notice. Set
   the PROVIDER_AIVEN_ENABLE_BETA environment variable to use the resource.
 ---
 
 # aiven_organization_application_user_token (Resource)
 
-Creates and manages an organization application user token in Aiven. 
+Creates and manages an application user token. Review the [best practices](https://aiven.io/docs/platform/concepts/application-users#security-best-practices) for securing application users and their tokens. 
+
 **This resource is in the beta stage and may change without notice.** Set
 the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to use the resource.
 
+## Example Usage
+
+```terraform
+resource "aiven_organization_application_user" "tf_user" {
+  organization_id = aiven_organization.main.id
+  name = "app-terraform"
+}
 
+resource "aiven_organization_application_user_token" "example" {
+  organization_id = aiven_organization.main.id
+  user_id = aiven_organization_application_user.tf_user.user_id
+  description = "Token for TF access to Aiven."
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
-- `organization_id` (String) Identifier of the organization the application user token belongs to.
-- `user_id` (String) Identifier of the application user the token belongs to.
+- `organization_id` (String) The ID of the organization the application user belongs to.
+- `user_id` (String) The ID of the application user the token is created for.
 
 ### Optional
 
 - `description` (String) Description of the token.
-- `extend_when_used` (Boolean) True to extend token expiration time when token is used. Only applicable if max_age_seconds is specified.
-- `max_age_seconds` (Number) Time the token remains valid since creation (or since last use if extend_when_used is true).
-- `scopes` (Set of String) Scopes this token is restricted to if specified.
+- `extend_when_used` (Boolean) Extends the token session duration when the token is used. Only applicable if a value is set for `max_age_seconds`.
+- `max_age_seconds` (Number) The number of hours after which a token expires. Default session duration is 10 hours.
+- `scopes` (Set of String) Restricts the scopes for this token.
 - `timeouts` (Block, Optional) (see [below for nested schema](#nestedblock--timeouts))
 
 ### Read-Only
 
 - `create_time` (String) Time when the token was created.
-- `created_manually` (Boolean) True for tokens explicitly created via the access_tokens API, false for tokens created via login.
-- `currently_active` (Boolean) True if API request was made with this access token.
-- `expiry_time` (String) Timestamp when the access token will expire unless extended, if ever.
+- `created_manually` (Boolean) True for tokens explicitly created using the `access_tokens` API. False for tokens created when a user logs in.
+- `currently_active` (Boolean) True if the API request was made with this token.
+- `expiry_time` (String) Timestamp when the access token will expire unless extended.
 - `full_token` (String, Sensitive) Full token.
-- `id` (String) Compound identifier of the organization application user token.
+- `id` (String) Compound identifier of the application user token.
 - `last_ip` (String) IP address of the last request made with this token.
-- `last_used_time` (String) Timestamp when the access token was last used, if ever.
+- `last_used_time` (String) Timestamp when the access token was last used.
 - `last_user_agent` (String) User agent of the last request made with this token.
 - `last_user_agent_human_readable` (String) User agent of the last request made with this token in human-readable format.
 - `token_prefix` (String) Prefix of the token.
@@ -55,3 +69,11 @@ Optional:
 - `delete` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours). Setting a timeout for a Delete operation is only applicable if changes are saved into state before the destroy operation occurs.
 - `read` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours). Read operations occur during any refresh or planning operation when refresh is enabled.
 - `update` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours).
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+terraform import aiven_organization_application_user_token.example ORGANIZATION_ID/USER_ID/TOKEN_PREFIX
+```

docs/resources/organization_group_project.md

@@ -11,6 +11,7 @@ description: |-
 # aiven_organization_group_project (Resource)
 
 Adds and manages a [group](https://aiven.io/docs/platform/concepts/projects_accounts_access#groups) of users as [members of a project](https://aiven.io/docs/platform/reference/project-member-privileges). 
+
 **This resource is in the beta stage and may change without notice.** Set
 the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to use the resource.
 

docs/resources/organization_user_group_member.md

@@ -11,6 +11,7 @@ description: |-
 # aiven_organization_user_group_member (Resource)
 
 Adds and manages users in a [user group](https://aiven.io/docs/platform/concepts/projects_accounts_access#groups). 
+
 **This resource is in the beta stage and may change without notice.** Set
 the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to use the resource.
 

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

@@ -0,0 +1,4 @@
+data "aiven_organization_application_user" "tf_user" {
+  organization_id = aiven_organization.main.id
+  user_id = "u123a456b7890c"
+}

examples/resources/aiven_organization_application_user/import.sh

@@ -0,0 +1 @@
+terraform import aiven_organization_application_user.example ORGANIZATION_ID/USER_ID

examples/resources/aiven_organization_application_user/resource.tf

@@ -0,0 +1,4 @@
+resource "aiven_organization_application_user" "tf_user" {
+  organization_id = aiven_organization.main.id
+  name = "app-terraform"
+}

examples/resources/aiven_organization_application_user_token/import.sh

@@ -0,0 +1 @@
+terraform import aiven_organization_application_user_token.example ORGANIZATION_ID/USER_ID/TOKEN_PREFIX

examples/resources/aiven_organization_application_user_token/resource.tf

@@ -0,0 +1,10 @@
+resource "aiven_organization_application_user" "tf_user" {
+  organization_id = aiven_organization.main.id
+  name = "app-terraform"
+}
+
+resource "aiven_organization_application_user_token" "example" {
+  organization_id = aiven_organization.main.id
+  user_id = aiven_organization_application_user.tf_user.user_id
+  description = "Token for TF access to Aiven."
+}

internal/plugin/service/organization/organization_application_user.go

@@ -81,39 +81,41 @@ func (r *organizationApplicationUser) Schema(
 	resp.Schema = util.GeneralizeSchema(ctx, schema.Schema{
 		Description: userconfig.
 			Desc(
-				"Creates and manages an organization application user. Application users can be used for " +
+				"Creates and manages an organization application user. [Application users](https://aiven.io/docs/platform/howto/manage-application-users) can be used for " +
 					"programmatic access to the platform.",
 			).
 			AvailabilityType(userconfig.Limited).
 			Build(),
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
-				Description: "Compound identifier of the organization application user.",
+				Description: "A compound identifier of the resource in the format `organization_id/user_id`.",
 				Computed:    true,
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.UseStateForUnknown(),
 				},
 			},
 			"organization_id": schema.StringAttribute{
-				Description: "Identifier of the organization the application user belongs to.",
+				Description: "The ID of the organization the application user belongs to.",
 				Required:    true,
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.RequiresReplace(),
 				},
 			},
 			"user_id": schema.StringAttribute{
-				Description: "Identifier of the organization application user.",
+				Description: "The ID of the application user.",
 				Computed:    true,
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.UseStateForUnknown(),
 				},
 			},
 			"name": schema.StringAttribute{
-				Description: "Name of the organization application user.",
+				Description: "Name of the application user.",
 				Required:    true,
 			},
 			"email": schema.StringAttribute{
-				Description: "Email of the organization application user.",
+				Description: `An email address automatically generated by Aiven to help identify the application user. 
+				No notifications are sent to this email.
+				`,
 				Computed:    true,
 			},
 		},

internal/plugin/service/organization/organization_application_user_data_source.go

@@ -9,6 +9,7 @@ import (
 	"github.com/hashicorp/terraform-plugin-framework/types"
 
 	"github.com/aiven/terraform-provider-aiven/internal/plugin/util"
+	"github.com/aiven/terraform-provider-aiven/internal/schemautil/userconfig"
 )
 
 var (
@@ -67,22 +68,28 @@ func (r *organizationApplicationUserDataSource) Schema(
 	resp *datasource.SchemaResponse,
 ) {
 	resp.Schema = schema.Schema{
-		Description: "Retrieves information about an organization application user from Aiven.",
+		Description: userconfig.
+		Desc(
+			"Gets information about an application user.",
+		).
+		MarkAsDataSource().
+		AvailabilityType(userconfig.Limited).
+		Build(),
 		Attributes: map[string]schema.Attribute{
 			"organization_id": schema.StringAttribute{
-				Description: "Identifier of the organization the application user belongs to.",
+				Description: "The ID of the organization the application user belongs to.",
 				Required:    true,
 			},
 			"user_id": schema.StringAttribute{
-				Description: "Identifier of the organization application user.",
+				Description: "The ID of the application user.",
 				Required:    true,
 			},
 			"name": schema.StringAttribute{
-				Description: "Name of the organization application user.",
+				Description: "Name of the application user.",
 				Computed:    true,
 			},
 			"email": schema.StringAttribute{
-				Description: "Email of the organization application user.",
+				Description: "The auto-generated email address of the application user.",
 				Computed:    true,
 			},
 		},