Skip to content

Remove Multiple Team Tokens from existing TFE release docs #1094

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Remove Multiple Team Tokens from existing TFE release docs #1094

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions content/terraform-docs-common/docs/cloud-docs/api-docs/team-tokens.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
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 |
| ------- | ------------------------------------------------------- | ------------------------------------------------------------ |
Expand Down Expand Up @@ -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 |
|----------------------|----------------------------------------------------------|
Expand Down
277 changes: 9 additions & 268 deletions content/terraform-enterprise/1.0.x/docs/enterprise/api-docs/team-tokens.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
---

Expand Down Expand Up @@ -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: <required>`) - 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: <required>`) - 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

Expand All @@ -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

Expand Down Expand Up @@ -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.

Expand Down
8 changes: 2 additions & 6 deletions ...aform-enterprise/1.0.x/docs/enterprise/users-teams-organizations/api-tokens.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,9 @@ API tokens may belong directly to a user. User tokens are the most flexible toke

Copy link
Contributor Author

@jacob-comer jacob-comer Oct 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I kept the link to [Users](/terraform/enterprise/users-teams-organizations/users#tokens) on line 19 that was introduced in the original PR, as that still seems valid after reverting the MTT changes.

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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 one valid API token at a time. When a token is regenerated, the previous token immediately becomes invalid.

Per the style guide, we should only use bold for UI elements and introducing new terms.


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.

Expand Down
2 changes: 1 addition & 1 deletion ...form-enterprise/1.0.x/docs/enterprise/users-teams-organizations/permissions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Loading
Loading