Support creation of multiple team tokens

CHANGELOG.md

@@ -3,6 +3,8 @@
 ## Enhancements
 
 * Remove `DefaultProject` from `OrganizationUpdateOptions` to prevent updating an organization's default project, by @netramali [#1078](https://github.com/hashicorp/go-tfe/pull/1078)
+* Adds support for creating multiple team tokens by adding `Description` to `TeamTokenCreateOptions`. This provides BETA support, which is EXPERIMENTAL, SUBJECT TO CHANGE, and may not be available to all users, by @mkam [#1083](https://github.com/hashicorp/go-tfe/pull/1083)
+* Adds support for reading and deleting team tokens by ID, by @mkam [#1083](https://github.com/hashicorp/go-tfe/pull/1083)
 
 ## BREAKING CHANGES
 

agent_token.go

@@ -116,7 +116,7 @@ func (s *agentTokens) Read(ctx context.Context, agentTokenID string) (*AgentToke
 		return nil, ErrInvalidAgentTokenID
 	}
 
-	u := fmt.Sprintf("authentication-tokens/%s", url.PathEscape(agentTokenID))
+	u := fmt.Sprintf(AuthenticationTokensPath, url.PathEscape(agentTokenID))
 	req, err := s.client.NewRequest("GET", u, nil)
 	if err != nil {
 		return nil, err
@@ -137,7 +137,7 @@ func (s *agentTokens) Delete(ctx context.Context, agentTokenID string) error {
 		return ErrInvalidAgentTokenID
 	}
 
-	u := fmt.Sprintf("authentication-tokens/%s", url.PathEscape(agentTokenID))
+	u := fmt.Sprintf(AuthenticationTokensPath, url.PathEscape(agentTokenID))
 	req, err := s.client.NewRequest("DELETE", u, nil)
 	if err != nil {
 		return err

const.go

@@ -0,0 +1,8 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package tfe
+
+const (
+	AuthenticationTokensPath = "authentication-tokens/%s"
+)

errors.go

@@ -236,6 +236,8 @@ var (
 	ErrInvalidAccessToken = errors.New("invalid value for access token")
 
 	ErrInvalidTaskResultsCallbackStatus = fmt.Errorf("invalid value for task result status. Must be either `%s`, `%s`, or `%s`", TaskFailed, TaskPassed, TaskRunning)
+
+	ErrInvalidDescriptionConflict = errors.New("invalid attributes\n\nValidation failed: Description has already been taken")
 )
 
 var (

helper_test.go

@@ -2196,7 +2196,7 @@ func createTeamTokenWithOptions(t *testing.T, client *Client, tm *Team, options
 	}
 
 	return tt, func() {
-		if err := client.TeamTokens.Delete(ctx, tm.ID); err != nil {
+		if err := client.TeamTokens.DeleteByID(ctx, tt.ID); err != nil {
 			t.Errorf("Error destroying team token! WARNING: Dangling resources\n"+
 				"may exist! The full error is shown below.\n\n"+
 				"TeamToken: %s\nError: %s", tm.ID, err)

team_token.go

@@ -19,17 +19,26 @@ var _ TeamTokens = (*teamTokens)(nil)
 // TFE API docs:
 // https://developer.hashicorp.com/terraform/cloud-docs/api-docs/team-tokens
 type TeamTokens interface {
-	// Create a new team token, replacing any existing token.
+	// Create a new team token using the legacy creation behavior, which creates a token without a description
+	// or regenerates the existing, descriptionless token.
 	Create(ctx context.Context, teamID string) (*TeamToken, error)
 
-	// CreateWithOptions a new team token, with options, replacing any existing token.
+	// CreateWithOptions creates a team token, with options. If no description is provided, it uses the legacy
+	// creation behavior, which regenerates the descriptionless token if it already exists. Otherwise, it create
+	//  a new token with the given unique description, allowing for the creation of multiple team tokens.
 	CreateWithOptions(ctx context.Context, teamID string, options TeamTokenCreateOptions) (*TeamToken, error)
 
-	// Read a team token by its ID.
+	// Read a team token by its team ID.
 	Read(ctx context.Context, teamID string) (*TeamToken, error)
 
-	// Delete a team token by its ID.
+	// Read a team token by its token ID.
+	ReadByID(ctx context.Context, teamID string) (*TeamToken, error)
+
+	// Delete a team token by its team ID.
 	Delete(ctx context.Context, teamID string) error
+
+	// Delete a team token by its token ID.
+	DeleteByID(ctx context.Context, tokenID string) error
 }
 
 // teamTokens implements TeamTokens.
@@ -46,27 +55,41 @@ type TeamToken struct {
 	Token       string           `jsonapi:"attr,token"`
 	ExpiredAt   time.Time        `jsonapi:"attr,expired-at,iso8601"`
 	CreatedBy   *CreatedByChoice `jsonapi:"polyrelation,created-by"`
+	Team        *Team            `jsonapi:"relation,team"`
 }
 
 // TeamTokenCreateOptions contains the options for creating a team token.
 type TeamTokenCreateOptions struct {
 	// Optional: The token's expiration date.
 	// This feature is available in TFE release v202305-1 and later
 	ExpiredAt *time.Time `jsonapi:"attr,expired-at,iso8601,omitempty"`
+
+	// Optional: The token's description, which must unique per team.
+	// This feature is considered BETA, SUBJECT TO CHANGE, and likely unavailable to most users.
+	Description string `jsonapi:"attr,description,omitempty"`
 }
 
-// Create a new team token, replacing any existing token.
+// Create a new team token using the legacy creation behavior, which creates a token without a description
+// or regenerates the existing, descriptionless token.
 func (s *teamTokens) Create(ctx context.Context, teamID string) (*TeamToken, error) {
 	return s.CreateWithOptions(ctx, teamID, TeamTokenCreateOptions{})
 }
 
-// CreateWithOptions a new team token, with options, replacing any existing token.
+// CreateWithOptions creates a team token, with options. If no description is provided, it uses the legacy
+// creation behavior, which regenerates the descriptionless token if it already exists. Otherwise, it create
+// a new token with the given unique description, allowing for the creation of multiple team tokens.
 func (s *teamTokens) CreateWithOptions(ctx context.Context, teamID string, options TeamTokenCreateOptions) (*TeamToken, error) {
 	if !validStringID(&teamID) {
 		return nil, ErrInvalidTeamID
 	}
 
-	u := fmt.Sprintf("teams/%s/authentication-token", url.PathEscape(teamID))
+	var u string
+	if options.Description != "" {
+		u = fmt.Sprintf("teams/%s/authentication-tokens", url.PathEscape(teamID))
+	} else {
+		u = fmt.Sprintf("teams/%s/authentication-token", url.PathEscape(teamID))
+	}
+
 	req, err := s.client.NewRequest("POST", u, &options)
 	if err != nil {
 		return nil, err
@@ -81,7 +104,7 @@ func (s *teamTokens) CreateWithOptions(ctx context.Context, teamID string, optio
 	return tt, err
 }
 
-// Read a team token by its ID.
+// Read a team token by its team ID.
 func (s *teamTokens) Read(ctx context.Context, teamID string) (*TeamToken, error) {
 	if !validStringID(&teamID) {
 		return nil, ErrInvalidTeamID
@@ -102,7 +125,28 @@ func (s *teamTokens) Read(ctx context.Context, teamID string) (*TeamToken, error
 	return tt, err
 }
 
-// Delete a team token by its ID.
+// Read a team token by its token ID.
+func (s *teamTokens) ReadByID(ctx context.Context, tokenID string) (*TeamToken, error) {
+	if !validStringID(&tokenID) {
+		return nil, ErrInvalidTokenID
+	}
+
+	u := fmt.Sprintf(AuthenticationTokensPath, url.PathEscape(tokenID))
+	req, err := s.client.NewRequest("GET", u, nil)
+	if err != nil {
+		return nil, err
+	}
+
+	tt := &TeamToken{}
+	err = req.Do(ctx, tt)
+	if err != nil {
+		return nil, err
+	}
+
+	return tt, err
+}
+
+// Delete a team token by its team ID.
 func (s *teamTokens) Delete(ctx context.Context, teamID string) error {
 	if !validStringID(&teamID) {
 		return ErrInvalidTeamID
@@ -116,3 +160,18 @@ func (s *teamTokens) Delete(ctx context.Context, teamID string) error {
 
 	return req.Do(ctx, nil)
 }
+
+// Delete a team token by its token ID.
+func (s *teamTokens) DeleteByID(ctx context.Context, tokenID string) error {
+	if !validStringID(&tokenID) {
+		return ErrInvalidTokenID
+	}
+
+	u := fmt.Sprintf(AuthenticationTokensPath, url.PathEscape(tokenID))
+	req, err := s.client.NewRequest("DELETE", u, nil)
+	if err != nil {
+		return err
+	}
+
+	return req.Do(ctx, nil)
+}