From 9c771a3ccea391f3f38749c4e4ac41e192455b47 Mon Sep 17 00:00:00 2001 From: Jacob Comer Date: Fri, 10 Oct 2025 15:06:13 -0400 Subject: [PATCH] Remove Multiple Team Tokens from existing TFE release docs --- .../docs/cloud-docs/api-docs/team-tokens.mdx | 10 +- .../docs/enterprise/api-docs/team-tokens.mdx | 277 +----------------- .../users-teams-organizations/api-tokens.mdx | 8 +- .../users-teams-organizations/permissions.mdx | 2 +- .../docs/enterprise/api-docs/team-tokens.mdx | 277 +----------------- .../users-teams-organizations/api-tokens.mdx | 8 +- .../users-teams-organizations/permissions.mdx | 2 +- .../docs/enterprise/api-docs/team-tokens.mdx | 277 +----------------- .../users-teams-organizations/api-tokens.mdx | 8 +- .../users-teams-organizations/permissions.mdx | 2 +- .../docs/enterprise/api-docs/team-tokens.mdx | 277 +----------------- .../users-teams-organizations/api-tokens.mdx | 8 +- .../users-teams-organizations/permissions.mdx | 2 +- 13 files changed, 53 insertions(+), 1105 deletions(-) diff --git a/content/terraform-docs-common/docs/cloud-docs/api-docs/team-tokens.mdx b/content/terraform-docs-common/docs/cloud-docs/api-docs/team-tokens.mdx index 9b6adfea31..d381eff982 100644 --- a/content/terraform-docs-common/docs/cloud-docs/api-docs/team-tokens.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/api-docs/team-tokens.mdx @@ -161,13 +161,13 @@ curl \ ## List team tokens -Lists the team tokens for the team. +Lists the team tokens for the organization with the option to filter by team name. -`GET /organizations/:organization_id/team-tokens` +`GET /organizations/:organization_name/team-tokens` | Parameter | Description | |----------------------|----------------------------------------------------------| -| `:organization_id` | The ID of the organization whose team tokens you want to list. | +| `:organization_name` | The name 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. @@ -257,7 +257,7 @@ Use this endpoint to display a particular [team token](/terraform/cloud-docs/use | ----------- | ------------------------- | | `: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 | | ------- | ------------------------------------------------------- | ------------------------------------------------------------ | @@ -416,7 +416,7 @@ curl \ Lists the [team tokens](/terraform/cloud-docs/users-teams-organizations/teams#api-tokens) in an organization. -`GET organizations/:organization_name/team-tokens` +`GET /organizations/:organization_name/team-tokens` | Parameter | Description | |----------------------|----------------------------------------------------------| diff --git a/content/terraform-enterprise/1.0.x/docs/enterprise/api-docs/team-tokens.mdx b/content/terraform-enterprise/1.0.x/docs/enterprise/api-docs/team-tokens.mdx index 9db2a1196a..87237c84bc 100644 --- a/content/terraform-enterprise/1.0.x/docs/enterprise/api-docs/team-tokens.mdx +++ b/content/terraform-enterprise/1.0.x/docs/enterprise/api-docs/team-tokens.mdx @@ -1,8 +1,8 @@ --- -page_title: '/teams/:team_id/authentication-tokens API reference for Terraform Enterprise' +page_title: /teams/authentication-token API reference for Terraform Enterprise description: >- - Use the Terraform Enterprise API's `/teams/:team_id/authentication-tokens` - endpoint to generate, delete, and list a team's API tokens. + Use the Terraform Enterprise API's `/teams/authentication-token` endpoint to + generate, delete, and list a team's API tokens. source: terraform-docs-common --- @@ -40,266 +40,7 @@ source: terraform-docs-common # 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 associated with a specific user. - -Teams relying on the [**legacy**](/terraform/enterprise/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. - -## 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 the secret text when you create it and cannot 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-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. | - -### Sample payload - -```json -{ - "data": { - "type": "authentication-tokens", - "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 a 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/enterprise/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/enterprise/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 - -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/enterprise/api-docs/team-tokens) includes the same functionality as legacy team tokens, and allows you to provision multiple tokens with descriptions per team. +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. ## Generate a new team token @@ -309,7 +50,7 @@ Generates a new team token and overrides existing token if one exists. | :----- | :----------------------------------- | | POST | /teams/:team_id/authentication-token | -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 this token when you create it and can not recover it later. ### Parameters @@ -494,19 +235,19 @@ This endpoint supports pagination [with standard URL query parameters](/terrafor Use this endpoint to display a [team token](/terraform/enterprise/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 text is only shown upon creation, and cannot be recovered later. diff --git a/content/terraform-enterprise/1.0.x/docs/enterprise/users-teams-organizations/api-tokens.mdx b/content/terraform-enterprise/1.0.x/docs/enterprise/users-teams-organizations/api-tokens.mdx index 4e66f88d03..42101a7b18 100644 --- a/content/terraform-enterprise/1.0.x/docs/enterprise/users-teams-organizations/api-tokens.mdx +++ b/content/terraform-enterprise/1.0.x/docs/enterprise/users-teams-organizations/api-tokens.mdx @@ -22,13 +22,9 @@ 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 Tokens** tab to manage API tokens for a team or create new team tokens. +Navigate to the **Organization settings > API Tokens > Team Token** 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 legacy token can exist at a given time. - -The [legacy API](/terraform/enterprise/api-docs/team-tokens#legacy-team-tokens-api-reference) uses a legacy token, generating a new legacy token invalidates the previous token. - -The [current team token API](/terraform/enterprise/api-docs/team-tokens#team-tokens-api-reference) supports multiple team tokens, and adding new tokens does not invalidate older ones. +Each team can have **one** valid API token at a time. When a token is regenerated, the previous token immediately becomes invalid. Owners and users with [manage teams](/terraform/enterprise/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/enterprise/users-teams-organizations/permissions#allow-member-token-management) for more information. diff --git a/content/terraform-enterprise/1.0.x/docs/enterprise/users-teams-organizations/permissions.mdx b/content/terraform-enterprise/1.0.x/docs/enterprise/users-teams-organizations/permissions.mdx index 73aa3cbdec..cb02db389d 100644 --- a/content/terraform-enterprise/1.0.x/docs/enterprise/users-teams-organizations/permissions.mdx +++ b/content/terraform-enterprise/1.0.x/docs/enterprise/users-teams-organizations/permissions.mdx @@ -360,7 +360,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, and revoke tokens. +Allows members to create, update, and delete teams, and generate, regenerate, 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. diff --git a/content/terraform-enterprise/v202505-1/docs/enterprise/api-docs/team-tokens.mdx b/content/terraform-enterprise/v202505-1/docs/enterprise/api-docs/team-tokens.mdx index 9db2a1196a..87237c84bc 100644 --- a/content/terraform-enterprise/v202505-1/docs/enterprise/api-docs/team-tokens.mdx +++ b/content/terraform-enterprise/v202505-1/docs/enterprise/api-docs/team-tokens.mdx @@ -1,8 +1,8 @@ --- -page_title: '/teams/:team_id/authentication-tokens API reference for Terraform Enterprise' +page_title: /teams/authentication-token API reference for Terraform Enterprise description: >- - Use the Terraform Enterprise API's `/teams/:team_id/authentication-tokens` - endpoint to generate, delete, and list a team's API tokens. + Use the Terraform Enterprise API's `/teams/authentication-token` endpoint to + generate, delete, and list a team's API tokens. source: terraform-docs-common --- @@ -40,266 +40,7 @@ source: terraform-docs-common # 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 associated with a specific user. - -Teams relying on the [**legacy**](/terraform/enterprise/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. - -## 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 the secret text when you create it and cannot 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-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. | - -### Sample payload - -```json -{ - "data": { - "type": "authentication-tokens", - "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 a 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/enterprise/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/enterprise/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 - -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/enterprise/api-docs/team-tokens) includes the same functionality as legacy team tokens, and allows you to provision multiple tokens with descriptions per team. +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. ## Generate a new team token @@ -309,7 +50,7 @@ Generates a new team token and overrides existing token if one exists. | :----- | :----------------------------------- | | POST | /teams/:team_id/authentication-token | -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 this token when you create it and can not recover it later. ### Parameters @@ -494,19 +235,19 @@ This endpoint supports pagination [with standard URL query parameters](/terrafor Use this endpoint to display a [team token](/terraform/enterprise/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 text is only shown upon creation, and cannot be recovered later. diff --git a/content/terraform-enterprise/v202505-1/docs/enterprise/users-teams-organizations/api-tokens.mdx b/content/terraform-enterprise/v202505-1/docs/enterprise/users-teams-organizations/api-tokens.mdx index 7ee9170593..c13824b8ea 100644 --- a/content/terraform-enterprise/v202505-1/docs/enterprise/users-teams-organizations/api-tokens.mdx +++ b/content/terraform-enterprise/v202505-1/docs/enterprise/users-teams-organizations/api-tokens.mdx @@ -22,13 +22,9 @@ 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 Tokens** tab to manage API tokens for a team or create new team tokens. +Navigate to the **Organization settings > API Tokens > Team Token** 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 legacy token can exist at a given time. - -The [legacy API](/terraform/enterprise/api-docs/team-tokens#legacy-team-tokens-api-reference) uses the legacy token, and generating a new legacy token invalidates the previous legacy token. - -The [current team token API](/terraform/enterprise/api-docs/team-tokens#team-tokens-api-reference) supports multiple team tokens, and adding new tokens does not invalidate older ones. +Each team can have **one** valid API token at a time. When a token is regenerated, the previous token immediately becomes invalid. Owners and users with [manage teams](/terraform/enterprise/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/enterprise/users-teams-organizations/permissions#allow-member-token-management) for more information. diff --git a/content/terraform-enterprise/v202505-1/docs/enterprise/users-teams-organizations/permissions.mdx b/content/terraform-enterprise/v202505-1/docs/enterprise/users-teams-organizations/permissions.mdx index 447737b7dc..1d0d03c03a 100644 --- a/content/terraform-enterprise/v202505-1/docs/enterprise/users-teams-organizations/permissions.mdx +++ b/content/terraform-enterprise/v202505-1/docs/enterprise/users-teams-organizations/permissions.mdx @@ -358,7 +358,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, and revoke tokens. +Allows members to create, update, and delete teams, and generate, regenerate, 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. diff --git a/content/terraform-enterprise/v202506-1/docs/enterprise/api-docs/team-tokens.mdx b/content/terraform-enterprise/v202506-1/docs/enterprise/api-docs/team-tokens.mdx index 9db2a1196a..87237c84bc 100644 --- a/content/terraform-enterprise/v202506-1/docs/enterprise/api-docs/team-tokens.mdx +++ b/content/terraform-enterprise/v202506-1/docs/enterprise/api-docs/team-tokens.mdx @@ -1,8 +1,8 @@ --- -page_title: '/teams/:team_id/authentication-tokens API reference for Terraform Enterprise' +page_title: /teams/authentication-token API reference for Terraform Enterprise description: >- - Use the Terraform Enterprise API's `/teams/:team_id/authentication-tokens` - endpoint to generate, delete, and list a team's API tokens. + Use the Terraform Enterprise API's `/teams/authentication-token` endpoint to + generate, delete, and list a team's API tokens. source: terraform-docs-common --- @@ -40,266 +40,7 @@ source: terraform-docs-common # 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 associated with a specific user. - -Teams relying on the [**legacy**](/terraform/enterprise/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. - -## 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 the secret text when you create it and cannot 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-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. | - -### Sample payload - -```json -{ - "data": { - "type": "authentication-tokens", - "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 a 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/enterprise/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/enterprise/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 - -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/enterprise/api-docs/team-tokens) includes the same functionality as legacy team tokens, and allows you to provision multiple tokens with descriptions per team. +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. ## Generate a new team token @@ -309,7 +50,7 @@ Generates a new team token and overrides existing token if one exists. | :----- | :----------------------------------- | | POST | /teams/:team_id/authentication-token | -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 this token when you create it and can not recover it later. ### Parameters @@ -494,19 +235,19 @@ This endpoint supports pagination [with standard URL query parameters](/terrafor Use this endpoint to display a [team token](/terraform/enterprise/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 text is only shown upon creation, and cannot be recovered later. diff --git a/content/terraform-enterprise/v202506-1/docs/enterprise/users-teams-organizations/api-tokens.mdx b/content/terraform-enterprise/v202506-1/docs/enterprise/users-teams-organizations/api-tokens.mdx index 9b9fbd1d33..77a5f589bf 100644 --- a/content/terraform-enterprise/v202506-1/docs/enterprise/users-teams-organizations/api-tokens.mdx +++ b/content/terraform-enterprise/v202506-1/docs/enterprise/users-teams-organizations/api-tokens.mdx @@ -22,13 +22,9 @@ 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 Tokens** tab to manage API tokens for a team or create new team tokens. +Navigate to the **Organization settings > API Tokens > Team Token** 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 legacy token can exist at a given time. - -The [legacy API](/terraform/enterprise/api-docs/team-tokens#legacy-team-tokens-api-reference) only operate on the legacy token. Generating a new legacy token invalidates the previous legacy token. - -The [non-legacy API](/terraform/enterprise/api-docs/team-tokens#team-tokens-api-reference) supports multiple valid team tokens. When a new token is generated, existing tokens remain valid. +Each team can have **one** valid API token at a time. When a token is regenerated, the previous token immediately becomes invalid. Owners and users with [manage teams](/terraform/enterprise/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/enterprise/users-teams-organizations/permissions#allow-member-token-management) for more information. diff --git a/content/terraform-enterprise/v202506-1/docs/enterprise/users-teams-organizations/permissions.mdx b/content/terraform-enterprise/v202506-1/docs/enterprise/users-teams-organizations/permissions.mdx index fa811d7de7..ed871ba888 100644 --- a/content/terraform-enterprise/v202506-1/docs/enterprise/users-teams-organizations/permissions.mdx +++ b/content/terraform-enterprise/v202506-1/docs/enterprise/users-teams-organizations/permissions.mdx @@ -360,7 +360,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, and revoke tokens. +Allows members to create, update, and delete teams, and generate, regenerate, 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. diff --git a/content/terraform-enterprise/v202507-1/docs/enterprise/api-docs/team-tokens.mdx b/content/terraform-enterprise/v202507-1/docs/enterprise/api-docs/team-tokens.mdx index 9db2a1196a..87237c84bc 100644 --- a/content/terraform-enterprise/v202507-1/docs/enterprise/api-docs/team-tokens.mdx +++ b/content/terraform-enterprise/v202507-1/docs/enterprise/api-docs/team-tokens.mdx @@ -1,8 +1,8 @@ --- -page_title: '/teams/:team_id/authentication-tokens API reference for Terraform Enterprise' +page_title: /teams/authentication-token API reference for Terraform Enterprise description: >- - Use the Terraform Enterprise API's `/teams/:team_id/authentication-tokens` - endpoint to generate, delete, and list a team's API tokens. + Use the Terraform Enterprise API's `/teams/authentication-token` endpoint to + generate, delete, and list a team's API tokens. source: terraform-docs-common --- @@ -40,266 +40,7 @@ source: terraform-docs-common # 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 associated with a specific user. - -Teams relying on the [**legacy**](/terraform/enterprise/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. - -## 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 the secret text when you create it and cannot 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-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. | - -### Sample payload - -```json -{ - "data": { - "type": "authentication-tokens", - "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 a 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/enterprise/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/enterprise/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 - -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/enterprise/api-docs/team-tokens) includes the same functionality as legacy team tokens, and allows you to provision multiple tokens with descriptions per team. +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. ## Generate a new team token @@ -309,7 +50,7 @@ Generates a new team token and overrides existing token if one exists. | :----- | :----------------------------------- | | POST | /teams/:team_id/authentication-token | -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 this token when you create it and can not recover it later. ### Parameters @@ -494,19 +235,19 @@ This endpoint supports pagination [with standard URL query parameters](/terrafor Use this endpoint to display a [team token](/terraform/enterprise/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 text is only shown upon creation, and cannot be recovered later. diff --git a/content/terraform-enterprise/v202507-1/docs/enterprise/users-teams-organizations/api-tokens.mdx b/content/terraform-enterprise/v202507-1/docs/enterprise/users-teams-organizations/api-tokens.mdx index a122bce2d0..77a5f589bf 100644 --- a/content/terraform-enterprise/v202507-1/docs/enterprise/users-teams-organizations/api-tokens.mdx +++ b/content/terraform-enterprise/v202507-1/docs/enterprise/users-teams-organizations/api-tokens.mdx @@ -22,13 +22,9 @@ 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 Tokens** tab to manage API tokens for a team or create new team tokens. +Navigate to the **Organization settings > API Tokens > Team Token** 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 legacy token can exist at a given time. - -The [legacy API](/terraform/enterprise/api-docs/team-tokens#legacy-team-tokens-api-reference) only operates on the legacy token. Generating a new legacy token invalidates the previous legacy token. - -The [current team token API](/terraform/enterprise/api-docs/team-tokens#team-tokens-api-reference) supports multiple team tokens. Adding new tokens does not invalidate existing tokens. +Each team can have **one** valid API token at a time. When a token is regenerated, the previous token immediately becomes invalid. Owners and users with [manage teams](/terraform/enterprise/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/enterprise/users-teams-organizations/permissions#allow-member-token-management) for more information. diff --git a/content/terraform-enterprise/v202507-1/docs/enterprise/users-teams-organizations/permissions.mdx b/content/terraform-enterprise/v202507-1/docs/enterprise/users-teams-organizations/permissions.mdx index fa811d7de7..ed871ba888 100644 --- a/content/terraform-enterprise/v202507-1/docs/enterprise/users-teams-organizations/permissions.mdx +++ b/content/terraform-enterprise/v202507-1/docs/enterprise/users-teams-organizations/permissions.mdx @@ -360,7 +360,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, and revoke tokens. +Allows members to create, update, and delete teams, and generate, regenerate, 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.