Skip to content

Commit 3184288

Browse files
jacob-comerjacob-comer
committed
Remove Multiple Team Tokens from existing TFE release docs
1 parent 70cd866 commit 3184288

File tree

13 files changed

+57
-1109
lines changed

13 files changed

+57
-1109
lines changed

‎content/terraform-docs-common/docs/cloud-docs/api-docs/team-tokens.mdx‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -161,13 +161,13 @@ curl \
161161

162162
## List team tokens
163163

164-
Lists the team tokens for the team.
164+
Lists the team tokens for the organization with the option to filter by team name.
165165

166-
`GET /organizations/:organization_id/team-tokens`
166+
`GET /organizations/:organization_name/team-tokens`
167167

168168
| Parameter | Description |
169169
|----------------------|----------------------------------------------------------|
170-
| `:organization_id` | The ID of the organization whose team tokens you want to list. |
170+
| `:organization_name` | The name of the organization whose team tokens you want to list. |
171171

172172
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.
173173

@@ -257,7 +257,7 @@ Use this endpoint to display a particular [team token](/terraform/cloud-docs/use
257257
| ----------- | ------------------------- |
258258
| `:token_id` | The ID of the Team Token. |
259259

260-
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.
260+
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.
261261

262262
| Status | Response | Reason |
263263
| ------- | ------------------------------------------------------- | ------------------------------------------------------------ |
@@ -416,7 +416,7 @@ curl \
416416

417417
Lists the [team tokens](/terraform/cloud-docs/users-teams-organizations/teams#api-tokens) in an organization.
418418

419-
`GET organizations/:organization_name/team-tokens`
419+
`GET /organizations/:organization_name/team-tokens`
420420

421421
| Parameter | Description |
422422
|----------------------|----------------------------------------------------------|

‎content/terraform-enterprise/1.0.x/docs/enterprise/api-docs/team-tokens.mdx‎

Lines changed: 10 additions & 269 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
---
2-
page_title: '/teams/:team_id/authentication-tokens API reference for Terraform Enterprise'
2+
page_title: /teams/authentication-token API reference for Terraform Enterprise
33
description: >-
4-
Use the Terraform Enterprise API's `/teams/:team_id/authentication-tokens`
5-
endpoint to generate, delete, and list a team's API tokens.
4+
Use the Terraform Enterprise API's `/teams/authentication-token` endpoint to
5+
generate, delete, and list a team's API tokens.
66
source: terraform-docs-common
77
---
88

@@ -40,266 +40,7 @@ source: terraform-docs-common
4040

4141
# Team tokens API reference
4242

43-
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.
44-
45-
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.
46-
47-
You can create and delete team tokens and list an organization's team tokens.
48-
49-
## Generate a new team token
50-
51-
Generates a new team token.
52-
53-
| Method | Path |
54-
| :----- | :------------------------------------ |
55-
| POST | /teams/:team_id/authentication-tokens |
56-
57-
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.
58-
59-
### Parameters
60-
61-
- `:team_id` (`string: <required>`) - specifies the team ID for generating the team token
62-
63-
### Request body
64-
65-
This POST endpoint requires a JSON object with the following properties as a request payload.
66-
67-
| Key path | Type | Default | Description |
68-
| ----------------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
69-
| `data.type` | string | | Must be `"authentication-tokens"`. |
70-
| `data.attributes.description` | string | | The description of the team token. Each description **must** be unique within the context of the team. |
71-
| `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. |
72-
73-
### Sample payload
74-
75-
```json
76-
{
77-
"data": {
78-
"type": "authentication-tokens",
79-
"attributes": {
80-
"description": "Team API token for team ABC",
81-
"expired-at": "2023-04-06T12:00:00.000Z"
82-
}
83-
}
84-
}
85-
```
86-
87-
### Sample request
88-
89-
```shell
90-
curl \
91-
--header "Authorization: Bearer $TOKEN" \
92-
--header "Content-Type: application/vnd.api+json" \
93-
--request POST \
94-
--data @payload.json \
95-
https://app.terraform.io/api/v2/teams/team-BUHBEM97xboT8TVz/authentication-tokens
96-
```
97-
98-
### Sample response
99-
100-
```json
101-
{
102-
"data": {
103-
"id": "4111797",
104-
"type": "authentication-tokens",
105-
"attributes": {
106-
"created-at": "2017-11-29T19:18:09.976Z",
107-
"last-used-at": null,
108-
"description": "Team API token for team ABC",
109-
"token": "QnbSxjjhVMHJgw.atlasv1.gxZnWIjI5j752DGqdwEUVLOFf0mtyaQ00H9bA1j90qWb254lEkQyOdfqqcq9zZL7Sm0",
110-
"expired-at": "2023-04-06T12:00:00.000Z"
111-
},
112-
"relationships": {
113-
"team": {
114-
"data": {
115-
"id": "team-Y7RyjccPVBKVEdp7",
116-
"type": "teams"
117-
}
118-
},
119-
"created-by": {
120-
"data": {
121-
"id": "user-62goNpx1ThQf689e",
122-
"type": "users"
123-
}
124-
}
125-
}
126-
}
127-
}
128-
129-
```
130-
131-
## Delete a team token
132-
133-
| Method | Path |
134-
| :----- | :------------------------------- |
135-
| DELETE | /authentication-tokens/:token_id |
136-
137-
### Parameters
138-
139-
- `:token_id` (`string: <required>`) - specifies the token_id from which to delete the token
140-
141-
### Sample request
142-
143-
```shell
144-
curl \
145-
--header "Authorization: Bearer $TOKEN" \
146-
--header "Content-Type: application/vnd.api+json" \
147-
--request DELETE \
148-
https://app.terraform.io/api/v2/authentication-tokens/at-6yEmxNAhaoQLH1Da
149-
```
150-
151-
## List team tokens
152-
153-
Lists the team tokens for the team.
154-
155-
`GET /organizations/:organization_id/team-tokens`
156-
157-
| Parameter | Description |
158-
| ------------------ | -------------------------------------------------------------- |
159-
| `:organization_id` | The ID of the organization whose team tokens you want to list. |
160-
161-
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.
162-
163-
| Status | Response | Reason |
164-
| ------- | --------------------------------------------- | -------------------------------------- |
165-
| [200][] | [JSON API document][] (`type: "team-tokens"`) | The request was successful. |
166-
| [200][] | Empty [JSON API document][] | The specified team has no team tokens. |
167-
| [404][] | [JSON API error object][] | Team not found. |
168-
169-
### Query parameters
170-
171-
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.
172-
173-
| Parameter | Description |
174-
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
175-
| `page[number]` | **Optional.** If omitted, the endpoint returns the first page. |
176-
| `page[size]` | **Optional.** If omitted, the endpoint returns 20 tokens per page. |
177-
| `q` | **Optional.** A search query string. You can search for a team authentication token using the team name. |
178-
| `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. |
179-
180-
### Sample response
181-
182-
```json
183-
{
184-
"data": [
185-
{
186-
"id": "at-TLhN8cc6ro6qYDvp",
187-
"type": "authentication-tokens",
188-
"attributes": {
189-
"created-at": "2017-11-29T19:18:09.976Z",
190-
"last-used-at": null,
191-
"description": "Team API token for team ABC",
192-
"token": "QnbSxjjhVMHJgw.atlasv1.gxZnWIjI5j752DGqdwEUVLOFf0mtyaQ00H9bA1j90qWb254lEkQyOdfqqcq9zZL7Sm0",
193-
"expired-at": "2023-04-06T12:00:00.000Z"
194-
},
195-
"relationships": {
196-
"team": {
197-
"data": {
198-
"id": "team-Y7RyjccPVBKVEdp7",
199-
"type": "teams"
200-
}
201-
},
202-
"created-by": {
203-
"data": {
204-
"id": "user-ccU6h629sszLJBpY",
205-
"type": "users"
206-
}
207-
}
208-
}
209-
},
210-
{
211-
"id": "at-qfc2wqqJ1T5sCamM",
212-
"type": "authentication-tokens",
213-
"attributes": {
214-
"created-at": "2024-06-19T18:44:44.051Z",
215-
"last-used-at": null,
216-
"description": "Team API token for team XYZ",
217-
"token": null,
218-
"expired-at": "2024-07-19T18:44:43.818Z"
219-
},
220-
"relationships": {
221-
"team": {
222-
"data": {
223-
"id": "team-58pFiBffTLMxLphR",
224-
"type": "teams"
225-
}
226-
},
227-
"created-by": {
228-
"data": {
229-
"id": "user-ccU6h629hhzLJBpY",
230-
"type": "users"
231-
}
232-
}
233-
}
234-
},
235-
]
236-
}
237-
```
238-
239-
## Show a team token
240-
241-
Use this endpoint to display a particular [team token](/terraform/enterprise/users-teams-organizations/teams#api-tokens).
242-
243-
`GET /authentication-tokens/:token_id`
244-
245-
| Parameter | Description |
246-
| ----------- | ------------------------- |
247-
| `:token_id` | The ID of the Team Token. |
248-
249-
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.
250-
251-
| Status | Response | Reason |
252-
| ------- | ------------------------------------------------------- | ------------------------------------------------------------ |
253-
| [200][] | [JSON API document][] (`type: "authentication-tokens"`) | The request was successful |
254-
| [404][] | [JSON API error object][] | Team Token not found, or unauthorized to view the Team Token |
255-
256-
### Sample request
257-
258-
```shell
259-
curl \
260-
--header "Authorization: Bearer $TOKEN" \
261-
--header "Content-Type: application/vnd.api+json" \
262-
--request GET \
263-
https://app.terraform.io/api/v2/authentication-tokens/at-6yEmxNAhaoQLH1Da
264-
```
265-
266-
### Sample response
267-
268-
```json
269-
{
270-
"data": {
271-
"id": "at-6yEmxNAhaoQLH1Da",
272-
"type": "authentication-tokens",
273-
"attributes": {
274-
"created-at": "2017-11-29T19:18:09.976Z",
275-
"last-used-at": null,
276-
"description": "Team API token for team ABC",
277-
"token": "QnbSxjjhVMHJgw.atlasv1.gxZnWIjI5j752DGqdwEUVLOFf0mtyaQ00H9bA1j90qWb254lEkQyOdfqqcq9zZL7Sm0",
278-
"expired-at": "2023-04-06T12:00:00.000Z"
279-
},
280-
"relationships": {
281-
"team": {
282-
"data": {
283-
"id": "team-LnREdjodkvZFGdXL",
284-
"type": "teams"
285-
}
286-
},
287-
"created-by": {
288-
"data": {
289-
"id": "user-MA4GL63FmYRpSFxa",
290-
"type": "users"
291-
}
292-
}
293-
}
294-
}
295-
}
296-
```
297-
298-
# Legacy team tokens API reference
299-
300-
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.
301-
You can create and delete team tokens and list an organization's team tokens.
302-
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.
43+
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.
30344

30445
## Generate a new team token
30546

@@ -309,7 +50,7 @@ Generates a new team token and overrides existing token if one exists.
30950
| :----- | :----------------------------------- |
31051
| POST | /teams/:team_id/authentication-token |
31152

312-
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.
53+
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.
31354

31455
### Parameters
31556

@@ -494,21 +235,21 @@ This endpoint supports pagination [with standard URL query parameters](/terrafor
494235

495236
Use this endpoint to display a [team token](/terraform/enterprise/users-teams-organizations/teams#api-tokens) for a particular team.
496237

497-
`GET /teams/:team_id/authentication-token`
238+
`GET /teams/:team-id/authentication-token`
498239

499240
| Parameter | Description |
500241
| ---------- | ------------------- |
501-
| `:team_id` | The ID of the Team. |
242+
| `:team-id` | The ID of the Team. |
502243

503244
You can also fetch a team token directly by using the token's ID with the `authentication-tokens/` endpoint.
504245

505-
`GET /authentication-tokens/:token_id`
246+
`GET /authentication-tokens/:token-id`
506247

507248
| Parameter | Description |
508249
| ----------- | ------------------------- |
509-
| `:token_id` | The ID of the Team Token. |
250+
| `:token-id` | The ID of the Team Token. |
510251

511-
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.
252+
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.
512253

513254
| Status | Response | Reason |
514255
| ------- | ------------------------------------------------------- | ------------------------------------------------------------ |

‎content/terraform-enterprise/1.0.x/docs/enterprise/users-teams-organizations/api-tokens.mdx‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,13 +22,9 @@ API tokens may belong directly to a user. User tokens are the most flexible toke
2222

2323
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.
2424

25-
Navigate to the **Organization Settings > API Tokens > Team Tokens** tab to manage API tokens for a team or create new team tokens.
25+
Navigate to the **Organization settings > API Tokens > Team Token** tab to manage API tokens for a team or create new team tokens.
2626

27-
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.
28-
29-
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.
30-
31-
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.
27+
Each team can have one valid API token at a time. When a token is regenerated, the previous token immediately becomes invalid.
3228

3329
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.
3430

‎content/terraform-enterprise/1.0.x/docs/enterprise/users-teams-organizations/permissions.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -360,7 +360,7 @@ In order to remove a user from the organization, the holder of this permission m
360360

361361
#### Manage Teams
362362

363-
Allows members to create, update, and delete teams, and generate, and revoke tokens.
363+
Allows members to create, update, and delete teams, and generate, regenerate, and revoke tokens.
364364

365365
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.
366366

0 commit comments

Comments
 (0)