From 58dddabf8f7f2491e6603feedf63d31c67708a90 Mon Sep 17 00:00:00 2001 From: Julianna Tetreault Date: Thu, 27 Mar 2025 11:41:29 -0500 Subject: [PATCH 1/6] Add API documentation for multi-team tokens and update exisiting docs --- .../docs/cloud-docs/api-docs/changelog.mdx | 4 + .../docs/cloud-docs/api-docs/team-tokens.mdx | 276 +++++++++++++++++- .../users-teams-organizations/api-tokens.mdx | 6 +- .../users-teams-organizations/permissions.mdx | 2 +- 4 files changed, 275 insertions(+), 13 deletions(-) diff --git a/website/docs/cloud-docs/api-docs/changelog.mdx b/website/docs/cloud-docs/api-docs/changelog.mdx index 3a16ca459..10dc16363 100644 --- a/website/docs/cloud-docs/api-docs/changelog.mdx +++ b/website/docs/cloud-docs/api-docs/changelog.mdx @@ -9,6 +9,10 @@ description: >- Keep track of changes to the API for HCP Terraform and Terraform Enterprise. +## 2025-03-20 +* Add API documentation for multiple [team tokens](/terraform/cloud-docs/api-docs/api-tokens), and update documentation around [legacy team tokens](/terraform/cloud-docs/api-docs/team-tokens##legacy-team-tokens-api-reference). +* Update existing API documentation for [team tokens](/terraform/cloud-docs/api-docs/team-tokens) to distinguish multiple team tokens from [legacy team tokens](/terraform/cloud-docs/api-docs/team-tokens##legacy-team-tokens-api-reference). + ## 2025-3-10 * Document unique pagination metadata given in the response of [Organization Runs Index API](/terraform/cloud-docs/api-docs/run##list-runs-in-an-organization). diff --git a/website/docs/cloud-docs/api-docs/team-tokens.mdx b/website/docs/cloud-docs/api-docs/team-tokens.mdx index 2c204bbda..f9cd97aca 100644 --- a/website/docs/cloud-docs/api-docs/team-tokens.mdx +++ b/website/docs/cloud-docs/api-docs/team-tokens.mdx @@ -1,7 +1,7 @@ --- -page_title: /teams/authentication-token API reference for HCP Terraform +page_title: /teams/:team_id/authentication-tokens API reference for HCP Terraform description: >- - Use the HCP Terraform API's `/teams/authentication-token` endpoint to generate, delete, and list a team's API tokens. + Use the HCP Terraform API's `/teams/:team_id/authentication-tokens` endpoint to generate, delete, and list a team's API tokens. --- [200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 @@ -38,7 +38,263 @@ description: >- # Team tokens API reference -Team API tokens grant access to a team's workspaces. Each team can have an API token that is not associated with a specific user. You can create and delete team tokens and list an organization's team tokens. +Team API tokens grant access to a team's workspaces. Teams are not limited to a single token, and can have multiple, valid tokens at a time. Team tokens are not are not associated with a specific user. + +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. + +You can create and delete team tokens and list an organization's team tokens. + +## Generate a new team token + +Generates a new team token. + +| Method | Path | +| :----- | :----------------------------------- | +| POST | /teams/:team_id/authentication-tokens | + +This endpoint returns the secret text of the new authentication token. You can only access this token when you create it and can not recover it later. + +### Parameters + +- `:team_id` (`string: `) - specifies the team ID for generating the team token + +### Request body + +This POST endpoint requires a JSON object with the following properties as a request payload. + + +| Key path | Type | Default | Description | +| ----------------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"authentication-token"`. | +| `data.attributes.description` | string | | The description of the team token. Each description **must** be unique within the context of the team. | +| `data.attributes.expired-at` | string | `null` | The UTC date and time that the Team Token will expire, in ISO 8601 format. If omitted or set to `null` the token will never expire. | + +### Sample payload + +```json +{ + "data": { + "type": "authentication-token", + "attributes": { + "description": "Team API token for team ABC", + "expired-at": "2023-04-06T12:00:00.000Z" + } + } +} +``` + +### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/teams/team-BUHBEM97xboT8TVz/authentication-tokens +``` + +### Sample response + +```json +{ + "data": { + "id": "4111797", + "type": "authentication-tokens", + "attributes": { + "created-at": "2017-11-29T19:18:09.976Z", + "last-used-at": null, + "description": "Team API token for team ABC", + "token": "QnbSxjjhVMHJgw.atlasv1.gxZnWIjI5j752DGqdwEUVLOFf0mtyaQ00H9bA1j90qWb254lEkQyOdfqqcq9zZL7Sm0", + "expired-at": "2023-04-06T12:00:00.000Z" + }, + "relationships": { + "team": { + "data": { + "id": "team-Y7RyjccPVBKVEdp7", + "type": "teams" + } + }, + "created-by": { + "data": { + "id": "user-62goNpx1ThQf689e", + "type": "users" + } + } + } + } +} + +``` + +## Delete the team token + +| Method | Path | +| :----- | :----------------------------------- | +| DELETE | /authentication-tokens/:token_id | + +### Parameters + +- `:token_id` (`string: `) - specifies the token_id from which to delete the token + +### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/authentication-tokens/at-6yEmxNAhaoQLH1Da +``` + +## List team tokens + +Lists the team tokens for the team. + +`GET /organizations/:organization_id/team-tokens` + +| Parameter | Description | +|----------------------|----------------------------------------------------------| +| `:organization_id` | The ID of the organization whose team tokens you want to list. | + +This endpoint returns object metadata and does not include secret authentication details of tokens. You can only view a token when you create it and cannot recover it later. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "team-tokens"`) | The request was successful. | +| [200][] | Empty [JSON API document][] | The specified team has no team tokens. | +| [404][] | [JSON API error object][] | Team not found. | + +### Query parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/cloud-docs/api-docs#query-parameters) and searching with the `q` parameter. Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +|----------------|---------------------------------------------------------------------| +| `page[number]` | **Optional.** If omitted, the endpoint returns the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint returns 20 tokens per page. | +| `q` | **Optional.** A search query string. You can search for a team authentication token using the team name. | +| `sort` | **Optional.** Allows sorting the team tokens by `"created-by"`, `"expired-at"`, and `"last-used-at"`. Prepending a hyphen to the sort parameter reverses the order. If omitted, the default sort order ascending. | + +### Sample response + +```json +{ + "data": [ + { + "id": "at-TLhN8cc6ro6qYDvp", + "type": "authentication-tokens", + "attributes": { + "created-at": "2017-11-29T19:18:09.976Z", + "last-used-at": null, + "description": "Team API token for team ABC", + "token": "QnbSxjjhVMHJgw.atlasv1.gxZnWIjI5j752DGqdwEUVLOFf0mtyaQ00H9bA1j90qWb254lEkQyOdfqqcq9zZL7Sm0", + "expired-at": "2023-04-06T12:00:00.000Z" + }, + "relationships": { + "team": { + "data": { + "id": "team-Y7RyjccPVBKVEdp7", + "type": "teams" + } + }, + "created-by": { + "data": { + "id": "user-ccU6h629sszLJBpY", + "type": "users" + } + } + } + }, + { + "id": "at-qfc2wqqJ1T5sCamM", + "type": "authentication-tokens", + "attributes": { + "created-at": "2024-06-19T18:44:44.051Z", + "last-used-at": null, + "description": "Team API token for team XYZ", + "token": null, + "expired-at": "2024-07-19T18:44:43.818Z" + }, + "relationships": { + "team": { + "data": { + "id": "team-58pFiBffTLMxLphR", + "type": "teams" + } + }, + "created-by": { + "data": { + "id": "user-ccU6h629hhzLJBpY", + "type": "users" + } + } + } + }, + ] +} +``` + +## Show a team token + +Use this endpoint to display a particular [team token](/terraform/cloud-docs/users-teams-organizations/teams#api-tokens). + +`GET /authentication-tokens/:token_id` + +| Parameter | Description | +| ----------- | ------------------------- | +| `:token_id` | The ID of the Team Token. | + +The object returned by this endpoint only contains metadata, and does not include the secret text of the authentication token. A token's secret test is only shown upon creation, and cannot be recovered later. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "authentication-tokens"`) | The request was successful | +| [404][] | [JSON API error object][] | Team Token not found, or unauthorized to view the Team Token | + +### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/authentication-tokens/at-6yEmxNAhaoQLH1Da +``` + +### Sample response + +```json +{ + "data": { + "id": "at-6yEmxNAhaoQLH1Da", + "type": "authentication-tokens", + "attributes": { + "created-at": "2017-11-29T19:18:09.976Z", + "last-used-at": null, + "description": "Team API token for team ABC", + "token": "QnbSxjjhVMHJgw.atlasv1.gxZnWIjI5j752DGqdwEUVLOFf0mtyaQ00H9bA1j90qWb254lEkQyOdfqqcq9zZL7Sm0", + "expired-at": "2023-04-06T12:00:00.000Z" + }, + "relationships": { + "team": { + "data": { + "id": "team-LnREdjodkvZFGdXL", + "type": "teams" + } + }, + "created-by": { + "data": { + "id": "user-MA4GL63FmYRpSFxa", + "type": "users" + } + } + } + } +} +``` + +# Legacy team tokens API reference ## Generate a new team token @@ -46,7 +302,7 @@ Generates a new team token and overrides existing token if one exists. | Method | Path | | :----- | :----------------------------------- | -| POST | /teams/:team_id/authentication-token | +| POST | /teams/:team_id/authentication-tokens | This endpoint returns the secret text of the new authentication token. You can only access this token when you create it and can not recover it later. @@ -62,6 +318,7 @@ This POST endpoint requires a JSON object with the following properties as a req | Key path | Type | Default | Description | | ----------------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------- | | `data.type` | string | | Must be `"authentication-token"`. | +| `data.attributes.description` | string | `null` | The description of the team token, if supplied, otherwise the description will be `null`. The description **must** be unique within the context of the team, meaning legacy tokens may only have one `null` or one descriptive description at a time. | | `data.attributes.expired-at` | string | `null` | The UTC date and time that the Team Token will expire, in ISO 8601 format. If omitted or set to `null` the token will never expire. | ### Sample payload @@ -85,7 +342,7 @@ curl \ --header "Content-Type: application/vnd.api+json" \ --request POST \ --data @payload.json \ - https://app.terraform.io/api/v2/teams/team-BUHBEM97xboT8TVz/authentication-token + https://app.terraform.io/api/v2/teams/team-BUHBEM97xboT8TVz/authentication-tokens ``` ### Sample response @@ -234,19 +491,19 @@ This endpoint supports pagination [with standard URL query parameters](/terrafor Use this endpoint to display a [team token](/terraform/cloud-docs/users-teams-organizations/teams#api-tokens) for a particular team. -`GET /teams/:team-id/authentication-token` +`GET /teams/:team_id/authentication-token` | Parameter | Description | | ---------- | ------------------------- | -| `:team-id` | The ID of the Team. | +| `:team_id` | The ID of the Team. | You can also fetch a team token directly by using the token's ID with the `authentication-tokens/` endpoint. -`GET /authentication-tokens/:token-id` +`GET /authentication-tokens/:token_id` | Parameter | Description | | ----------- | ------------------------- | -| `:token-id` | The ID of the Team Token. | +| `:token_id` | The ID of the Team Token. | The object returned by this endpoint only contains metadata, and does not include the secret text of the authentication token. A token's secret test is only shown upon creation, and cannot be recovered later. @@ -296,4 +553,3 @@ curl \ } } ``` - diff --git a/website/docs/cloud-docs/users-teams-organizations/api-tokens.mdx b/website/docs/cloud-docs/users-teams-organizations/api-tokens.mdx index c4a5787d1..0ba44d16d 100644 --- a/website/docs/cloud-docs/users-teams-organizations/api-tokens.mdx +++ b/website/docs/cloud-docs/users-teams-organizations/api-tokens.mdx @@ -14,7 +14,7 @@ Refer to [Team Token API](/terraform/cloud-docs/api-docs/team-tokens) and [Organ ## User API Tokens -API tokens may belong directly to a user. User tokens are the most flexible token type because they inherit permissions from the user they are associated with. For more information on user tokens and how to generate them, see the [Users](/terraform/cloud-docs/users-teams-organizations/users#api-tokens) documentation. +API tokens may belong directly to a user. User tokens are the most flexible token type because they inherit permissions from the user they are associated with. For more information on user tokens and how to generate them, see the [Users](/terraform/cloud-docs/users-teams-organizations/users#tokens) documentation. ## Team API Tokens @@ -22,7 +22,9 @@ API tokens may belong to a specific team. Team API tokens allow access to the wo Navigate to the **Organization settings > API Tokens > Team Token** tab to manage API tokens for a team or create new team tokens. -Each team can have **one** valid API token at a time. When a token is regenerated, the previous token immediately becomes invalid. +Each team can have multiple, valid API tokens at a time, unless the team is using the legacy team token API. + +For teams relying on the [**legacy**](/terraform/cloud-docs/api-docs/team-tokens#legacy-team-tokens-api-reference) team token API, each team can only have **one** valid API token at a time. When a legacy team token is generated, the previous token immediately becomes invalid. Owners and users with [manage teams](/terraform/cloud-docs/users-teams-organizations/permissions#manage-teams) permissions have the ability to enable and disable team token management for a team, which limits the actions that team members can take on a team token. Refer to [Allow Member Token Management](/terraform/cloud-docs/users-teams-organizations/permissions#allow-member-token-management) for more information. diff --git a/website/docs/cloud-docs/users-teams-organizations/permissions.mdx b/website/docs/cloud-docs/users-teams-organizations/permissions.mdx index 5358f0919..5b37ee0ca 100644 --- a/website/docs/cloud-docs/users-teams-organizations/permissions.mdx +++ b/website/docs/cloud-docs/users-teams-organizations/permissions.mdx @@ -331,7 +331,7 @@ In order to remove a user from the organization, the holder of this permission m #### Manage Teams -Allows members to create, update, and delete teams, and generate, regenerate, and revoke tokens. +Allows members to create, update, and delete teams, and generate, and revoke tokens. This permission grants the ability to update a team's names, SSO IDs, and token management permissions, but does not allow access to organization settings. On its own, this permission does not allow users to create, update, delete, or otherwise access secret teams. From ab9e30eaa23a8b1f553ce7c8df3d2bd3c9b69f98 Mon Sep 17 00:00:00 2001 From: Julianna Tetreault Date: Mon, 14 Apr 2025 12:38:14 -0500 Subject: [PATCH 2/6] Apply code review suggestions --- website/docs/cloud-docs/api-docs/team-tokens.mdx | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/website/docs/cloud-docs/api-docs/team-tokens.mdx b/website/docs/cloud-docs/api-docs/team-tokens.mdx index f9cd97aca..0b08563c6 100644 --- a/website/docs/cloud-docs/api-docs/team-tokens.mdx +++ b/website/docs/cloud-docs/api-docs/team-tokens.mdx @@ -38,7 +38,7 @@ description: >- # Team tokens API reference -Team API tokens grant access to a team's workspaces. Teams are not limited to a single token, and can have multiple, valid tokens at a time. Team tokens are not are not associated with a specific user. +Team API tokens grant access to a team's workspaces. Teams are not limited to a single token, and can have multiple tokens at a time. Team tokens are not are not associated with a specific user. 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. @@ -52,7 +52,7 @@ Generates a new team token. | :----- | :----------------------------------- | | POST | /teams/:team_id/authentication-tokens | -This endpoint returns the secret text of the new authentication token. You can only access this token when you create it and can not recover it later. +This endpoint returns the secret text of the new authentication token. You can only access the secret when you create it and cannot recover it later. ### Parameters @@ -127,7 +127,7 @@ curl \ ``` -## Delete the team token +## Delete a team token | Method | Path | | :----- | :----------------------------------- | @@ -296,15 +296,19 @@ curl \ # Legacy team tokens API reference +Legacy team API tokens grant access to a team's workspaces. Each team can have an API token that is not associated with a specific user. +You can create and delete team tokens and list an organization's team tokens. +The [team tokens API](/terraform/cloud-docs/api-docs/team-tokens) includes the same functionality as legacy team tokens, and allows you to provision multiple tokens per team. + ## Generate a new team token Generates a new team token and overrides existing token if one exists. | Method | Path | | :----- | :----------------------------------- | -| POST | /teams/:team_id/authentication-tokens | +| POST | /teams/:team_id/authentication-token | -This endpoint returns the secret text of the new authentication token. You can only access this token when you create it and can not recover it later. +This endpoint returns the secret text of the new authentication token. You can only access the secret when you create it and cannot recover it later. ### Parameters From 0aeb1c7093e7f61e210e9f7b801ccee13fb9cade Mon Sep 17 00:00:00 2001 From: Julianna Tetreault Date: Wed, 23 Apr 2025 11:16:07 -0500 Subject: [PATCH 3/6] Address PR feedback: Add more info to distinguish legacy tokens --- website/docs/cloud-docs/api-docs/team-tokens.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/docs/cloud-docs/api-docs/team-tokens.mdx b/website/docs/cloud-docs/api-docs/team-tokens.mdx index 0b08563c6..2c66b80b4 100644 --- a/website/docs/cloud-docs/api-docs/team-tokens.mdx +++ b/website/docs/cloud-docs/api-docs/team-tokens.mdx @@ -40,7 +40,7 @@ description: >- Team API tokens grant access to a team's workspaces. Teams are not limited to a single token, and can have multiple tokens at a time. Team tokens are not are not associated with a specific user. -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 create a **single**, valid token at a time. Generating a new legacy token when one already exists for the team revokes the existing legacy token, replacing it with a new team token. You can create and delete team tokens and list an organization's team tokens. @@ -298,7 +298,7 @@ curl \ Legacy team API tokens grant access to a team's workspaces. Each team can have an API token that is not associated with a specific user. You can create and delete team tokens and list an organization's team tokens. -The [team tokens API](/terraform/cloud-docs/api-docs/team-tokens) includes the same functionality as legacy team tokens, and allows you to provision multiple tokens per team. +The [team tokens API](/terraform/cloud-docs/api-docs/team-tokens) includes the same functionality as legacy team tokens, and allows you to provision multiple tokens with descriptions per team. ## Generate a new team token @@ -346,7 +346,7 @@ curl \ --header "Content-Type: application/vnd.api+json" \ --request POST \ --data @payload.json \ - https://app.terraform.io/api/v2/teams/team-BUHBEM97xboT8TVz/authentication-tokens + https://app.terraform.io/api/v2/teams/team-BUHBEM97xboT8TVz/authentication-token ``` ### Sample response From f3a6bf940eed75d01d52ccf0864b53a52f415d46 Mon Sep 17 00:00:00 2001 From: Julianna Tetreault Date: Wed, 23 Apr 2025 11:25:09 -0500 Subject: [PATCH 4/6] Update type to be plural (authentication-tokens rather than authentication-token) --- website/docs/cloud-docs/api-docs/team-tokens.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/docs/cloud-docs/api-docs/team-tokens.mdx b/website/docs/cloud-docs/api-docs/team-tokens.mdx index 2c66b80b4..e1339eec2 100644 --- a/website/docs/cloud-docs/api-docs/team-tokens.mdx +++ b/website/docs/cloud-docs/api-docs/team-tokens.mdx @@ -38,9 +38,9 @@ description: >- # Team tokens API reference -Team API tokens grant access to a team's workspaces. Teams are not limited to a single token, and can have multiple tokens at a time. Team tokens are not are not associated with a specific user. +Team API tokens grant access to a team's workspaces. Teams are not limited to a single token, and can have multiple tokens at a time. Team tokens are not associated with a specific user. -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 create a **single**, valid token at a time. Generating a new legacy token when one already exists for the team revokes the existing legacy token, replacing it with a new team token. +Teams relying on the [**legacy**](/terraform/cloud-docs/api-docs/team-tokens#legacy-team-tokens-api-reference) team token API (`/teams/:team_id/authentication-token`), can only create a **single**, valid token at a time. Generating a new legacy token when one already exists for the team revokes the existing legacy token, replacing it with a new team token. You can create and delete team tokens and list an organization's team tokens. @@ -65,7 +65,7 @@ This POST endpoint requires a JSON object with the following properties as a req | Key path | Type | Default | Description | | ----------------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------- | -| `data.type` | string | | Must be `"authentication-token"`. | +| `data.type` | string | | Must be `"authentication-tokens"`. | | `data.attributes.description` | string | | The description of the team token. Each description **must** be unique within the context of the team. | | `data.attributes.expired-at` | string | `null` | The UTC date and time that the Team Token will expire, in ISO 8601 format. If omitted or set to `null` the token will never expire. | @@ -74,7 +74,7 @@ This POST endpoint requires a JSON object with the following properties as a req ```json { "data": { - "type": "authentication-token", + "type": "authentication-tokens", "attributes": { "description": "Team API token for team ABC", "expired-at": "2023-04-06T12:00:00.000Z" From 6129993fcc7abc7b9f29d18e089222eaa83a471b Mon Sep 17 00:00:00 2001 From: Julianna Tetreault Date: Wed, 23 Apr 2025 15:54:41 -0500 Subject: [PATCH 5/6] Update api-tokens.mdx team tokens description --- .../cloud-docs/users-teams-organizations/api-tokens.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/website/docs/cloud-docs/users-teams-organizations/api-tokens.mdx b/website/docs/cloud-docs/users-teams-organizations/api-tokens.mdx index 0ba44d16d..cb1c20b8d 100644 --- a/website/docs/cloud-docs/users-teams-organizations/api-tokens.mdx +++ b/website/docs/cloud-docs/users-teams-organizations/api-tokens.mdx @@ -20,11 +20,13 @@ API tokens may belong directly to a user. User tokens are the most flexible toke API tokens may belong to a specific team. Team API tokens allow access to the workspaces that the team has access to, without being tied to any specific user. -Navigate to the **Organization settings > API Tokens > Team Token** tab to manage API tokens for a team or create new team tokens. +Navigate to the **Organization Settings > API Tokens > Team Tokens** tab to manage API tokens for a team or create new team tokens. -Each team can have multiple, valid API tokens at a time, unless the team is using the legacy team token API. +Teams can have multiple valid tokens at a time, so long as the tokens' descriptions are unique within the context of the given team. A token without a description is considered a legacy token, and only one, descriptionless token can exist at a given time. -For teams relying on the [**legacy**](/terraform/cloud-docs/api-docs/team-tokens#legacy-team-tokens-api-reference) team token API, each team can only have **one** valid API token at a time. When a legacy team token is generated, the previous token immediately becomes invalid. +The [**legacy API**](/terraform/cloud-docs/api-docs/team-tokens#legacy-team-tokens-api-reference) will only operate on the legacy token, and generating a new legacy token invalidates the previous legacy token. + +The [**non-legacy API**](/terraform/cloud-docs/api-docs/team-tokens#team-tokens-api-reference) will support the existence of multiple, valid team tokens, meaning that when a new, non-legacy token is generated, existing tokens will remain valid. Owners and users with [manage teams](/terraform/cloud-docs/users-teams-organizations/permissions#manage-teams) permissions have the ability to enable and disable team token management for a team, which limits the actions that team members can take on a team token. Refer to [Allow Member Token Management](/terraform/cloud-docs/users-teams-organizations/permissions#allow-member-token-management) for more information. From 98d1064d48b440f8766993ff81980e632c9d0289 Mon Sep 17 00:00:00 2001 From: Julianna Tetreault Date: Thu, 24 Apr 2025 11:20:35 -0500 Subject: [PATCH 6/6] Apply code review suggestions for api- and team-tokens --- website/docs/cloud-docs/api-docs/team-tokens.mdx | 7 +++---- .../cloud-docs/users-teams-organizations/api-tokens.mdx | 2 +- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/website/docs/cloud-docs/api-docs/team-tokens.mdx b/website/docs/cloud-docs/api-docs/team-tokens.mdx index e1339eec2..6d745e2c5 100644 --- a/website/docs/cloud-docs/api-docs/team-tokens.mdx +++ b/website/docs/cloud-docs/api-docs/team-tokens.mdx @@ -52,7 +52,7 @@ Generates a new team token. | :----- | :----------------------------------- | | POST | /teams/:team_id/authentication-tokens | -This endpoint returns the secret text of the new authentication token. You can only access the secret when you create it and cannot recover it later. +This endpoint returns the secret text of the new authentication token. You can only access the secret text when you create it and cannot recover it later. ### Parameters @@ -296,7 +296,7 @@ curl \ # Legacy team tokens API reference -Legacy team API tokens grant access to a team's workspaces. Each team can have an API token that is not associated with a specific user. +Legacy team API tokens grant access to a team's workspaces. Each team can have a single legacy API token that is not associated with a specific user. You can create and delete team tokens and list an organization's team tokens. The [team tokens API](/terraform/cloud-docs/api-docs/team-tokens) includes the same functionality as legacy team tokens, and allows you to provision multiple tokens with descriptions per team. @@ -322,7 +322,6 @@ This POST endpoint requires a JSON object with the following properties as a req | Key path | Type | Default | Description | | ----------------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------- | | `data.type` | string | | Must be `"authentication-token"`. | -| `data.attributes.description` | string | `null` | The description of the team token, if supplied, otherwise the description will be `null`. The description **must** be unique within the context of the team, meaning legacy tokens may only have one `null` or one descriptive description at a time. | | `data.attributes.expired-at` | string | `null` | The UTC date and time that the Team Token will expire, in ISO 8601 format. If omitted or set to `null` the token will never expire. | ### Sample payload @@ -509,7 +508,7 @@ You can also fetch a team token directly by using the token's ID with the `authe | ----------- | ------------------------- | | `:token_id` | The ID of the Team Token. | -The object returned by this endpoint only contains metadata, and does not include the secret text of the authentication token. A token's secret test is only shown upon creation, and cannot be recovered later. +The object returned by this endpoint only contains metadata, and does not include the secret text of the authentication token. A token's secret text is only shown upon creation, and cannot be recovered later. | Status | Response | Reason | | ------- | ------------------------------------------------------- | ------------------------------------------------------------ | diff --git a/website/docs/cloud-docs/users-teams-organizations/api-tokens.mdx b/website/docs/cloud-docs/users-teams-organizations/api-tokens.mdx index cb1c20b8d..ffaec40f6 100644 --- a/website/docs/cloud-docs/users-teams-organizations/api-tokens.mdx +++ b/website/docs/cloud-docs/users-teams-organizations/api-tokens.mdx @@ -22,7 +22,7 @@ API tokens may belong to a specific team. Team API tokens allow access to the wo Navigate to the **Organization Settings > API Tokens > Team Tokens** tab to manage API tokens for a team or create new team tokens. -Teams can have multiple valid tokens at a time, so long as the tokens' descriptions are unique within the context of the given team. A token without a description is considered a legacy token, and only one, descriptionless token can exist at a given time. +Teams can have multiple valid tokens at a time, so long as the tokens' descriptions are unique within the context of the given team. A token without a description is considered a legacy token, and only one legacy token can exist at a given time. The [**legacy API**](/terraform/cloud-docs/api-docs/team-tokens#legacy-team-tokens-api-reference) will only operate on the legacy token, and generating a new legacy token invalidates the previous legacy token.