docs: add LA note and update app users

docs/data-sources/organization_application_user.md

@@ -3,24 +3,31 @@
 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.
 ---
 
 # aiven_organization_application_user (Data Source)
 
-Retrieves information about an organization application user from Aiven.
+Gets information about an application user.
 
+## 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,37 +3,47 @@
 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 features is in the limited availability stage. Contact [email protected] to try this feature.
-  This resource is in beta and may change without notice. To use this resource,
-  set the PROVIDER_AIVEN_ENABLE_BETA environment variable to true.
+  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 you can use this resource by
+  setting the PROVIDER_AIVEN_ENABLE_BETA environment variable to true.
 ---
 
 # aiven_organization_application_user (Resource)
 
-Creates and manages an organization application user. Application users can be used for programmatic access to the platform. This features is in the limited availability stage. Contact [email protected] to try this feature.
+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 beta and may change without notice.** To use this resource, 
-set the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to true.
+**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 you can use this resource by
+setting the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to true.
 
+## 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) The 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`
@@ -44,3 +54,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,46 +3,61 @@
 page_title: "aiven_organization_application_user_token Resource - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  Creates and manages an organization application user token in Aiven.
-  This resource is in beta and may change without notice. To use this resource,
-  set the PROVIDER_AIVEN_ENABLE_BETA environment variable to true.
+  Creates and manages an authentication token for an application user in Aiven. 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 limited availability stage and may change without notice. To enable this feature,
+  contact the sales team mailto:[email protected]. After it's enabled you can use this resource by
+  setting the PROVIDER_AIVEN_ENABLE_BETA environment variable to true.
 ---
 
 # aiven_organization_application_user_token (Resource)
 
-Creates and manages an organization application user token in Aiven.
+Creates and manages an authentication token for an application user in Aiven. 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 beta and may change without notice.** To use this resource, 
-set the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to true.
+**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 you can use this resource by
+setting the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to true.
 
+## 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 = "Auth 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 belongs to.
 
 ### 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's 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.
@@ -56,3 +71,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
+```

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 = "Auth token for TF access to Aiven."
+}

internal/plugin/service/organization/organization_application_user.go

@@ -78,36 +78,38 @@ func (r *organizationApplicationUser) Schema(
 	resp *resource.SchemaResponse,
 ) {
 	resp.Schema = util.GeneralizeSchema(ctx, schema.Schema{
-		Description: util.BetaDescription("Creates and manages an organization application user. Application users can be used for programmatic access to the platform. This features is in the limited availability stage. Contact [email protected] to try this feature."),
+		Description: util.LimitedAvailabilityDescription("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."),
 		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: "The name of the application user.",
 				Required:    true,
 			},
 			"email": schema.StringAttribute{
-				Description: "Email of the organization application user.",
-				Computed:    true,
+				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

@@ -67,22 +67,22 @@ func (r *organizationApplicationUserDataSource) Schema(
 	resp *datasource.SchemaResponse,
 ) {
 	resp.Schema = schema.Schema{
-		Description: "Retrieves information about an organization application user from Aiven.",
+		Description: "Gets information about an application user.",
 		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,
 			},
 		},

internal/plugin/service/organization/organization_application_user_token.go

@@ -108,24 +108,25 @@ func (r *organizationApplicationUserToken) Schema(
 	resp *resource.SchemaResponse,
 ) {
 	resp.Schema = util.GeneralizeSchema(ctx, schema.Schema{
-		Description: util.BetaDescription("Creates and manages an organization application user token in Aiven."),
+		Description: util.LimitedAvailabilityDescription("Creates and manages an authentication token for an application user in Aiven." +
+			" Review the [best practices](https://aiven.io/docs/platform/concepts/application-users#security-best-practices) for securing application users and their tokens."),
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
-				Description: "Compound identifier of the organization application user token.",
+				Description: "Compound identifier of the application user's token.",
 				Computed:    true,
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.UseStateForUnknown(),
 				},
 			},
 			"organization_id": schema.StringAttribute{
-				Description: "Identifier of the organization the application user token 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 application user the token belongs to.",
+				Description: "The ID of the application user the token belongs to.",
 				Required:    true,
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.RequiresReplace(),
@@ -151,52 +152,51 @@ func (r *organizationApplicationUserToken) Schema(
 				},
 			},
 			"max_age_seconds": schema.NumberAttribute{
-				Description: "Time the token remains valid since creation (or since last use if " +
-					"extend_when_used is true).",
-				Optional: true,
+				Description: "The number of hours after which a token expires. Default session duration is 10 hours.",
+				Optional:    true,
 				PlanModifiers: []planmodifier.Number{
 					numberplanmodifier.RequiresReplace(),
 				},
 			},
 			"extend_when_used": schema.BoolAttribute{
-				Description: "True to extend token expiration time when token is used. Only applicable if " +
-					"max_age_seconds is specified.",
+				Description: "Extends the token session duration when the token is used. Only applicable if " +
+					"a value is set for `max_age_seconds`.",
 				Optional: true,
 				PlanModifiers: []planmodifier.Bool{
 					boolplanmodifier.RequiresReplace(),
 				},
 			},
 			"scopes": schema.SetAttribute{
-				Description: "Scopes this token is restricted to if specified.",
+				Description: "Restricts the scopes for this token.",
 				Optional:    true,
 				ElementType: types.StringType,
 				PlanModifiers: []planmodifier.Set{
 					setplanmodifier.RequiresReplace(),
 				},
 			},
 			"currently_active": schema.BoolAttribute{
-				Description: "True if API request was made with this access token.",
+				Description: "True if the API request was made with this token.",
 				Computed:    true,
 			},
 			"create_time": schema.StringAttribute{
 				Description: "Time when the token was created.",
 				Computed:    true,
 			},
 			"created_manually": schema.BoolAttribute{
-				Description: "True for tokens explicitly created via the access_tokens API, false for tokens created " +
-					"via login.",
+				Description: "True for tokens explicitly created using the `access_tokens` API. False for tokens created " +
+					"when a user logs in.",
 				Computed: true,
 			},
 			"expiry_time": schema.StringAttribute{
-				Description: "Timestamp when the access token will expire unless extended, if ever.",
+				Description: "Timestamp when the access token will expire unless extended.",
 				Computed:    true,
 			},
 			"last_ip": schema.StringAttribute{
 				Description: "IP address of the last request made with this token.",
 				Computed:    true,
 			},
 			"last_used_time": schema.StringAttribute{
-				Description: "Timestamp when the access token was last used, if ever.",
+				Description: "Timestamp when the access token was last used.",
 				Computed:    true,
 			},
 			"last_user_agent": schema.StringAttribute{