Add API Documentation for Multi-Team Tokens

[juliannatetreault]

What

Update the Team Token API documentation to reflect the changes to team tokens, which include allowing multiple team tokens to be generated for a team and flagging the existing Team Token API as "legacy."

Why

These updates are relevant to the work being done for the allowance of multiple team tokens. The work being done adds a new API endpoint for creating multiple team tokens and now requires that Team Tokens (using the new API) set a description for the token, similar to the user experience when creating User Tokens. The existing Team Token API that only allows a single team token to be created will still exist so that users leveraging that API do not have to worry about data loss, however, this API is considered to be "legacy" now. Additionally, the work being done includes changes to the regenerate token button in the UI--this button will cease to exist once the changes are rolled out. The API documentation does not mention this button much, so very small wording tweaks were made to reflect this. Here's a link to the RFC for more information regarding the updates, and the Jira ticket for the work.

---

Merge Checklist

If items do not apply to your changes, add (N/A) and mark them as complete.

Pull Request

• One or more labels describe the type of change (e.g. clarification) and associated product (e.g. HCP Terraform ).
• Description links to related pull requests or issues, if any.

Content

• Redirects have been added to website/redirects.js for moved, renamed, or deleted pages.
• API documentation and the API Changelog have been updated.
• Links to related content where appropriate (e.g., API endpoints, permissions, etc.).
• Pages with related content are updated and link to this content when appropriate.
• (N/A) Sidebar navigation files have been updated for added, deleted, reordered, or renamed pages.
• (N/A) New pages have metadata (page name and description) at the top.
• (N/A) New images are 2048 px wide. They have HashiCorp standard annotation color (#F92672) and format (rectangle with rounded corners), blurred sensitive details (e.g. credentials, usernames, user icons), and descriptive alt text in the markdown for accessibility.
• New code blocks have the correct syntax and line breaks to eliminate horizontal scroll bars.
• (N/A) UI elements (button names, page names, etc.) are bolded.
• The Vercel website preview successfully deployed.

Reviews

• I or someone else reviewed the content for technical accuracy.
• I or someone else reviewed the content for typos, punctuation, spelling, and grammar.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
terraform-docs-common	✅ Ready (Inspect)	Visit Preview	💬 1 unresolved	Apr 16, 2025 7:42pm

[juliannatetreault]

Rather than creating a brand new page for the new API, I decided to break the existing team token API documentation into two sections: "Team tokens API reference" and "Legacy team tokens API reference." Since both APIs will exist simultaneously, I didn't want to make the API tokens site navigation confusing, break existing references to this documentation, or create confusion for users who regularly use these docs. Furthermore, both the old and new API share a lot of the same background information and keeping the two coupled and reusing some of that information felt like the more straightforward thing to do. This all being said, though, I don't feel strongly about coupling or decoupling the two APIs and would love to hear what other folks think!

[robin-norwood]

A few suggestions.

[robin-norwood]

Suggested change

	Teams relying on the [**legacy**](/terraform/cloud-docs/api-docs/team-tokens#legacy-team-tokens-api-reference) team token API (`/teams/authentication-token`), can only have a **single**, valid token at a time. Generating a new legacy token revokes any previously existing tokens, replacing it with the new team token.
	Teams relying on the [**legacy**](/terraform/cloud-docs/api-docs/team-tokens#legacy-team-tokens-api-reference) team token API (`/teams/authentication-token`), can only have a **single**, valid token at a time. Generating a new legacy token revokes any previously existing tokens, replacing it with the new team token.

Does "revokes any previously existing tokens" include tokens under the /teams/:team_id/authentication-tokens endpoint, or just the legacy endpoint?

[juliannatetreault]

Just the legacy endpoint!