Add organization token support and unit tests

examples/organization_token.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""
+Organization Token Operations Example
+
+Demonstrates usage of all 6 organization token operations:
+1. create() - Create a new organization token, replacing any existing token
+2. create_with_options() - Create with options like expiration date and token type
+3. read() - Read the organization token
+4. read_with_options() - Read with options like token type
+5. delete() - Delete the organization token
+6. delete_with_options() - Delete with options like token type
+
+Usage:
+- Modify organization names as needed for your environment
+- Ensure you have proper TFE credentials and organization access
+- Organization tokens are used for organization-level API access
+
+Prerequisites:
+- Set TFE_TOKEN and TFE_ADDRESS environment variables
+- You need an existing organization or admin permissions to create one
+- Appropriate permissions to manage organization tokens
+"""
+
+from datetime import datetime, timedelta
+
+# Add the src directory to the path
+##sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+from pytfe import TFEClient, TFEConfig
+from pytfe.models import (
+    OrganizationTokenCreateOptions,
+    OrganizationTokenDeleteOptions,
+    OrganizationTokenReadOptions,
+    TokenType,
+)
+
+
+def redact_token(token_value: str | None) -> str:
+    """Redact token value for safe display."""
+    if not token_value:
+        return "None"
+    if len(token_value) <= 8:
+        return f"{'*' * len(token_value)}"
+    # Show first 3 and last 3 characters
+    return f"{token_value[:3]}...{token_value[-3:]}".replace(
+        token_value[3:-3], "*" * (len(token_value) - 6)
+    )
+
+
+def redact_id(id_value: str | None) -> str:
+    """Redact ID for safe display."""
+    if not id_value:
+        return "None"
+    if len(id_value) <= 6:
+        return f"{'*' * len(id_value)}"
+    # Show first 3 and last 3 characters
+    return f"{id_value[:3]}...{id_value[-3:]}"
+
+
+def main():
+    """Execute organization token operation examples."""
+
+    print("=" * 80)
+    print("ORGANIZATION TOKEN OPERATIONS")
+    print("=" * 80)
+
+    # Initialize the TFE client
+    client = TFEClient(TFEConfig.from_env())
+    organization_name = "prab-sandbox01"
+    # =====================================================
+    # 1. CREATE ORGANIZATION TOKEN (BASIC)
+    # =====================================================
+    print("\n1. create() - Create a new organization token:")
+    print("-" * 40)
+    try:
+        print(f"Creating token for organization: {organization_name}")
+        token = client.organization_tokens.create(organization_name)
+
+        print("Token created successfully!")
+        print(f"  Token ID: {redact_id(token.id)}")
+        print(f"  Created At: {token.created_at}")
+        print(f"  Description: {token.description}")
+        print(f"  Token Value: {redact_token(token.token)}")
+        if token.expired_at:
+            print(f"  Expires At: {token.expired_at}")
+        print()
+
+    except Exception as e:
+        print(f" Error: {e}")
+        print()
+
+    # =====================================================
+    # 2. CREATE WITH OPTIONS (WITH EXPIRATION)
+    # =====================================================
+    print("2. create_with_options() - Create token with expiration date:")
+    print("-" * 40)
+    try:
+        # Create a token that expires in 30 days
+        expiry_date = datetime.utcnow() + timedelta(days=30)
+        options = OrganizationTokenCreateOptions(expired_at=expiry_date)
+
+        print(f"Creating organization token with expiration date: {expiry_date}")
+        token = client.organization_tokens.create_with_options(
+            organization_name, options
+        )
+
+        print("Token created with options successfully!")
+        print(f"  Token ID: {redact_id(token.id)}")
+        print(f"  Created At: {token.created_at}")
+        if token.expired_at:
+            print(f"  Expires At: {token.expired_at}")
+        print()
+
+    except Exception as e:
+        print(f" Error: {e}")
+        print()
+
+    # =====================================================
+    print("3. create_with_options() - Create audit-trails token:")
+    print("-" * 40)
+    try:
+        options = OrganizationTokenCreateOptions(token_type=TokenType.AUDIT_TRAILS)
+
+        print(f"Creating audit-trails token for organization: {organization_name}")
+        token = client.organization_tokens.create_with_options(
+            organization_name, options
+        )
+
+        print(" Audit-trails token created successfully!")
+        print(f"  Token ID: {redact_id(token.id)}")
+        print(f"  Token Value: {redact_token(token.token)}")
+        print()
+
+    except Exception as e:
+        print(f"Error: {e}")
+        print()
+
+    # =====================================================
+    print("4. read() - Read the organization token:")
+    print("-" * 40)
+    try:
+        print(f"Reading organization token for organization: {organization_name}")
+        token = client.organization_tokens.read(organization_name)
+
+        print("Token read successfully!")
+        print(f"  Token ID: {redact_id(token.id)}")
+        print(f"  Created At: {token.created_at}")
+        print(f"  Description: {token.description}")
+        if token.last_used_at:
+            print(f"  Last Used At: {token.last_used_at}")
+        if token.expired_at:
+            print(f"  Expires At: {token.expired_at}")
+        print()
+
+    except Exception as e:
+        print(f" Error: {e}")
+        print()
+
+    # =====================================================
+    print("5. read_with_options() - Read audit-trails token:")
+    print("-" * 40)
+    try:
+        options = OrganizationTokenReadOptions(token_type=TokenType.AUDIT_TRAILS)
+
+        print(f"Reading audit-trails token for organization: {organization_name}")
+        token = client.organization_tokens.read_with_options(organization_name, options)
+
+        print(" Audit-trails token read successfully!")
+        print(f"  Token ID: {redact_id(token.id)}")
+        print(f"  Token Value: {redact_token(token.token)}")
+        print()
+
+    except Exception as e:
+        print(f" Error: {e}")
+        print()
+
+    # =====================================================
+    print("6. delete() - Delete the organization token:")
+    print("-" * 40)
+    try:
+        print(f"Deleting organization token for organization: {organization_name}")
+        client.organization_tokens.delete(organization_name)
+
+        print(" Token deleted successfully!")
+        print()
+
+    except Exception as e:
+        print(f" Error: {e}")
+        print()
+
+    # =====================================================
+    print("7. delete_with_options() - Delete audit-trails token:")
+    print("-" * 40)
+    try:
+        options = OrganizationTokenDeleteOptions(token_type=TokenType.AUDIT_TRAILS)
+
+        print(f"Deleting audit-trails token for organization: {organization_name}")
+        client.organization_tokens.delete_with_options(organization_name, options)
+
+        print(" Audit-trails token deleted successfully!")
+        print()
+
+    except Exception as e:
+        print(f"Error: {e}")
+        print()
+
+    print("=" * 80)
+    print("ORGANIZATION TOKEN OPERATIONS COMPLETED")
+    print("=" * 80)
+
+
+if __name__ == "__main__":
+    main()

src/pytfe/client.py

@@ -10,6 +10,7 @@
 from .resources.oauth_client import OAuthClients
 from .resources.oauth_token import OAuthTokens
 from .resources.organization_membership import OrganizationMemberships
+from .resources.organization_token import OrganizationTokens
 from .resources.organizations import Organizations
 from .resources.plan import Plans
 from .resources.policy import Policies
@@ -69,6 +70,7 @@ def __init__(self, config: TFEConfig | None = None):
         self.plans = Plans(self._transport)
         self.organizations = Organizations(self._transport)
         self.organization_memberships = OrganizationMemberships(self._transport)
+        self.organization_tokens = OrganizationTokens(self._transport)
         self.projects = Projects(self._transport)
         self.variables = Variables(self._transport)
         self.variable_sets = VariableSets(self._transport)

src/pytfe/models/__init__.py

@@ -93,6 +93,15 @@
     OrganizationMembershipStatus,
     OrgMembershipIncludeOpt,
 )
+
+# ── Organization Token ────────────────────────────────────────────────────────
+from .organization_token import (
+    OrganizationToken,
+    OrganizationTokenCreateOptions,
+    OrganizationTokenDeleteOptions,
+    OrganizationTokenReadOptions,
+    TokenType,
+)
 from .policy import (
     Policy,
     PolicyCreateOptions,
@@ -287,7 +296,6 @@
 from .ssh_key import (
     SSHKey,
     SSHKeyCreateOptions,
-    SSHKeyList,
     SSHKeyListOptions,
     SSHKeyUpdateOptions,
 )
@@ -382,7 +390,6 @@
     # SSH keys
     "SSHKey",
     "SSHKeyCreateOptions",
-    "SSHKeyList",
     "SSHKeyListOptions",
     "SSHKeyUpdateOptions",
     # Reserved tag keys
@@ -486,6 +493,12 @@
     "OrganizationMembershipReadOptions",
     "OrganizationMembershipStatus",
     "OrgMembershipIncludeOpt",
+    # Organization tokens
+    "OrganizationToken",
+    "OrganizationTokenCreateOptions",
+    "OrganizationTokenDeleteOptions",
+    "OrganizationTokenReadOptions",
+    "TokenType",
     "OrganizationAccess",
     "Team",
     "TeamPermissions",

src/pytfe/models/organization_token.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+if TYPE_CHECKING:
+    pass
+
+
+class TokenType(str, Enum):
+    """Token type enumeration."""
+
+    AUDIT_TRAILS = "audit-trails"
+
+
+class OrganizationToken(BaseModel):
+    """Organization token represents a Terraform Enterprise organization token."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str = Field(..., description="Organization token ID")
+    created_at: datetime = Field(..., description="Creation timestamp")
+    description: str | None = Field(None, description="Token description")
+    last_used_at: datetime | None = Field(None, description="Last usage timestamp")
+    token: str | None = Field(None, description="The actual token value")
+    expired_at: datetime | None = Field(None, description="Token expiration timestamp")
+    created_by: Any | None = Field(
+        None, description="The entity that created this token"
+    )
+
+
+class OrganizationTokenCreateOptions(BaseModel):
+    """Options for creating an organization token."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    expired_at: datetime | None = Field(
+        None,
+        description="The token's expiration date. Available in TFE release v202305-1 and later",
+    )
+    token_type: TokenType | None = Field(
+        None,
+        alias="token",
+        description="What type of token to create. Only applicable to HCP Terraform",
+    )
+
+
+class OrganizationTokenReadOptions(BaseModel):
+    """Options for reading an organization token."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    token_type: TokenType | None = Field(
+        None,
+        alias="token",
+        description="What type of token to read. Only applicable to HCP Terraform",
+    )
+
+
+class OrganizationTokenDeleteOptions(BaseModel):
+    """Options for deleting an organization token."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    token_type: TokenType | None = Field(
+        None,
+        alias="token",
+        description="What type of token to delete. Only applicable to HCP Terraform",
+    )