docs: clarify OAT authentication support (#130)

Author: lanwen

README.md

@@ -54,7 +54,8 @@ cat ~/my_password.txt | docker login --username my-username --password-stdin
 ```
 
 If you'd like to use a different account for running the provider,
-you can set credentials in the environment:
+you can set credentials in the environment. When using an organization access
+token (OAT), set `DOCKER_USERNAME` to the organization name:
 
 ```
 export DOCKER_USERNAME=my-username
@@ -78,6 +79,23 @@ Unfortunately, PATs are limited to managing repositories. If you'd like to use
 this provider to manage organizations and teams, you will need to authenticate
 with a password.
 
+Organization access tokens (OATs) are a separate credential type for
+organization-scoped automation. Authenticate with the organization name as the
+username and the OAT as the password.
+
+OATs can be used with this provider for organization APIs when the token has
+the required permissions for the target API, such as `Member Read`,
+`Member Edit`, `Invite Read`, `Invite Edit`, `Group Read`, and `Group Edit`.
+
+When the provider auto-resolves credentials from Docker's config file, it
+currently prefers Docker Desktop's cached access token before `docker login`
+pull credentials. If you want to force OAT usage, set `DOCKER_USERNAME` and
+`DOCKER_PASSWORD` explicitly or configure them in the provider block.
+
+Organization access tokens are incompatible with Docker Desktop, Image Access
+Management, and Registry Access Management. Use a password or PAT for those
+features.
+
 ## Contributing
 
 We welcome contributions to the Docker services Terraform provider, detailed documentation for contributing & building the provider can be found [here](https://github.com/docker/terraform-provider-docker/blob/main/CONTRIBUTING.md)

docs/data-sources/org.md

@@ -4,7 +4,7 @@ page_title: "docker_org Data Source - docker"
 subcategory: ""
 description: |-
   Reads properties of a Docker Hub organization.
-  -> Note: This data source is only available when authenticated with a username and password.
+  -> Note: This data source requires credentials that can access organization APIs, such as a user password or an organization access token (OAT) with the required organization permissions.
   Example Usage
   
   data "docker_org" "example" {
@@ -26,7 +26,7 @@ description: |-
 
 Reads properties of a Docker Hub organization.
 
--> **Note**: This data source is only available when authenticated with a username and password.
+-> **Note**: This data source requires credentials that can access organization APIs, such as a user password or an organization access token (OAT) with the required organization permissions.
 
 ## Example Usage
 

docs/data-sources/org_members.md

@@ -4,7 +4,7 @@ page_title: "docker_org_members Data Source - docker"
 subcategory: ""
 description: |-
   Reads members of an organization.
-  -> Note Only available when authenticated with a username and password.
+  -> Note Requires credentials that can read organization members, such as a user password or an organization access token (OAT) with the Member Read scope.
   Example Usage
   
   data "docker_org_members" "_" {
@@ -20,7 +20,7 @@ description: |-
 
 Reads members of an organization.
 
--> **Note** Only available when authenticated with a username and password.
+-> **Note** Requires credentials that can read organization members, such as a user password or an organization access token (OAT) with the `Member Read` scope.
 
 ## Example Usage
 

docs/data-sources/org_team.md

@@ -4,7 +4,7 @@ page_title: "docker_org_team Data Source - docker"
 subcategory: ""
 description: |-
   Reads team information within a Docker Hub organization.
-  -> Note: This data source is only available when authenticated with a username and password.
+  -> Note: This data source requires credentials that can read organization groups, such as a user password or an organization access token (OAT) with the Group Read scope.
   Example Usage
   
   data "docker_org_team" "example" {
@@ -26,7 +26,7 @@ description: |-
 
 Reads team information within a Docker Hub organization.
 
--> **Note**: This data source is only available when authenticated with a username and password.
+-> **Note**: This data source requires credentials that can read organization groups, such as a user password or an organization access token (OAT) with the `Group Read` scope.
 
 ## Example Usage
 

docs/data-sources/org_team_member.md

@@ -4,7 +4,7 @@ page_title: "docker_org_team_member Data Source - docker"
 subcategory: ""
 description: |-
   Reads team members of a specified team within a Docker Hub organization.
-  -> Note: This data source is only available when authenticated with a username and password.
+  -> Note: This data source requires credentials that can read organization groups, such as a user password or an organization access token (OAT) with the Group Read scope.
   Example Usage
   
   data "docker_org_team_member" "example" {
@@ -25,7 +25,7 @@ description: |-
 
 Reads team members of a specified team within a Docker Hub organization.
 
--> **Note**: This data source is only available when authenticated with a username and password.
+-> **Note**: This data source requires credentials that can read organization groups, such as a user password or an organization access token (OAT) with the `Group Read` scope.
 
 ## Example Usage
 

docs/index.md

@@ -58,7 +58,8 @@ description: |-
   
   Setting credentials with environment variables
   If you'd like to use a different account for running the provider,
-  you can set credentials in the environment:
+  you can set credentials in the environment. When using an organization access
+  token (OAT), set DOCKER_USERNAME to the organization name:
   
   export DOCKER_USERNAME=my-username
   export DOCKER_PASSWORD=my-secret-token
@@ -91,6 +92,21 @@ description: |-
   passwords.
   Unfortunately, PATs are limited to managing repositories. If you'd like to use
   this provider to manage organizations and teams, you will need to authenticate
+  with a password.
+  Organization access tokens (OATs) are a separate credential type for
+  organization-scoped automation. Authenticate with the organization name as the
+  username and the OAT as the password.
+  OATs can be used with this provider for organization APIs when the token has
+  the required permissions for the target API, such as Member Read,
+  Member Edit, Invite Read, Invite Edit,
+  Group Read, and Group Edit.
+  When the provider auto-resolves credentials from Docker's config file, it
+  currently prefers Docker Desktop's cached access token before docker login
+  pull credentials. If you want to force OAT usage, set DOCKER_USERNAME and
+  DOCKER_PASSWORD explicitly or configure them in the provider block.
+  Organization access tokens are incompatible with Docker Desktop, Image Access
+  Management, and Registry Access Management. Use a password or PAT for those
+  features.
 ---
 
 # docker Provider
@@ -169,7 +185,8 @@ jobs:
 ### Setting credentials with environment variables
 
 If you'd like to use a different account for running the provider,
-you can set credentials in the environment:
+you can set credentials in the environment. When using an organization access
+token (OAT), set `DOCKER_USERNAME` to the organization name:
 
 ```
 export DOCKER_USERNAME=my-username
@@ -219,6 +236,25 @@ passwords.
 
 Unfortunately, PATs are limited to managing repositories. If you'd like to use
 this provider to manage organizations and teams, you will need to authenticate
+with a password.
+
+Organization access tokens (OATs) are a separate credential type for
+organization-scoped automation. Authenticate with the organization name as the
+username and the OAT as the password.
+
+OATs can be used with this provider for organization APIs when the token has
+the required permissions for the target API, such as `Member Read`,
+`Member Edit`, `Invite Read`, `Invite Edit`,
+`Group Read`, and `Group Edit`.
+
+When the provider auto-resolves credentials from Docker's config file, it
+currently prefers Docker Desktop's cached access token before `docker login`
+pull credentials. If you want to force OAT usage, set `DOCKER_USERNAME` and
+`DOCKER_PASSWORD` explicitly or configure them in the provider block.
+
+Organization access tokens are incompatible with Docker Desktop, Image Access
+Management, and Registry Access Management. Use a password or PAT for those
+features.
 
 
 
@@ -229,5 +265,5 @@ this provider to manage organizations and teams, you will need to authenticate
 
 - `host` (String) Docker Hub API Host. Default is `hub.docker.com`.
 - `max_page_results` (Number) Maximum number of pages to fetch when retrieving paginated data. Default is 50. Set to 0 for unlimited pages.
-- `password` (String, Sensitive) Password for authentication
-- `username` (String) Username for authentication
+- `password` (String, Sensitive) Password, PAT, or OAT for authentication
+- `username` (String) Username or organization namespace for authentication

docs/resources/org_access_token.md

@@ -20,9 +20,8 @@ description: |-
     ]
     expires_at = "2027-12-31T23:59:59Z"
   }
-
-  For TYPE_REPO resources, path must point to an existing repository or a supported glob such as my-organization/*.
   
+  For TYPE_REPO resources, path must point to an existing repository or a supported glob such as my-organization/*.
   Public-Only Repositories
   Use the special path */*/public to scope the token to public repositories only.
   

docs/resources/org_member.md

@@ -4,7 +4,7 @@ page_title: "docker_org_member Resource - docker"
 subcategory: ""
 description: |-
   Manages members associated with an organization.
-  -> Note Only available when authenticated with a username and password as an owner of the org.
+  -> Note Requires credentials that can read and manage organization members and invites, such as an owner login with a user password or an organization access token (OAT) with the Member Read, Member Edit, Invite Read, and Invite Edit scopes.
   When a member is added to an organization, they don't have access to the
   organization's repositories until they accept the invitation. The invitation is
   sent to the email address associated with the user's Docker ID.
@@ -35,7 +35,7 @@ description: |-
 
 Manages members associated with an organization.
 
--> **Note** Only available when authenticated with a username and password as an owner of the org.
+-> **Note** Requires credentials that can read and manage organization members and invites, such as an owner login with a user password or an organization access token (OAT) with the `Member Read`, `Member Edit`, `Invite Read`, and `Invite Edit` scopes.
 
 When a member is added to an organization, they don't have access to the
 organization's repositories until they accept the invitation. The invitation is

docs/resources/org_setting_image_access_management.md

@@ -4,6 +4,7 @@ page_title: "docker_org_setting_image_access_management Resource - docker"
 subcategory: ""
 description: |-
   Manages the Image Access Management settings for an organization.
+  -> Note: Docker does not support organization access token (OAT) authentication for Image Access Management. Use a user password or PAT instead.
   Example Usage
   
   resource "docker_org_setting_image_access_management" "example" {
@@ -18,6 +19,8 @@ description: |-
 
 Manages the Image Access Management settings for an organization.
 
+-> **Note**: Docker does not support organization access token (OAT) authentication for Image Access Management. Use a user password or PAT instead.
+
 ## Example Usage
 
 ```hcl

docs/resources/org_setting_registry_access_management.md

@@ -4,6 +4,7 @@ page_title: "docker_org_setting_registry_access_management Resource - docker"
 subcategory: ""
 description: |-
   Manages the Registry Access Management settings for an organization.
+  -> Note: Docker does not support organization access token (OAT) authentication for Registry Access Management. Use a user password or PAT instead.
   Example Usage
   
   resource "docker_org_setting_registry_access_management" "example" {
@@ -31,6 +32,8 @@ description: |-
 
 Manages the Registry Access Management settings for an organization.
 
+-> **Note**: Docker does not support organization access token (OAT) authentication for Registry Access Management. Use a user password or PAT instead.
+
 ## Example Usage
 
 ```hcl