Skip to content

Commit 64ecdf0

Browse files
juliannatetreaultjuliannatetreault
committed
Add API documentation for multi-team tokens and update exisiting docs
1 parent c0a89ff commit 64ecdf0

File tree

4 files changed

+275
-13
lines changed

4 files changed

+275
-13
lines changed

‎website/docs/cloud-docs/api-docs/changelog.mdx

+4
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@ description: >-
99

1010
Keep track of changes to the API for HCP Terraform and Terraform Enterprise.
1111

12+
## 2025-03-20
13+
* Add API documentation for multiple [team tokens](/terraform/cloud-docs/api-docs/api-tokens), and update documentation around [legacy team tokens](/terraform/cloud-docs/api-docs/team-tokens##legacy-team-tokens-api-reference).
14+
* Update existing API documentation for [team tokens](/terraform/cloud-docs/api-docs/team-tokens) to distinguish multiple team tokens from [legacy team tokens](/terraform/cloud-docs/api-docs/team-tokens##legacy-team-tokens-api-reference).
15+
1216
## 2025-3-10
1317
* Document unique pagination metadata given in the response of [Organization Runs Index API](/terraform/cloud-docs/api-docs/run##list-runs-in-an-organization).
1418

‎website/docs/cloud-docs/api-docs/team-tokens.mdx

+266-10
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
page_title: /teams/authentication-token API reference for HCP Terraform
2+
page_title: /teams/:team_id/authentication-tokens API reference for HCP Terraform
33
description: >-
4-
Use the HCP Terraform API's `/teams/authentication-token` endpoint to generate, delete, and list a team's API tokens.
4+
Use the HCP Terraform API's `/teams/:team_id/authentication-tokens` endpoint to generate, delete, and list a team's API tokens.
55
---
66

77
[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200
@@ -38,15 +38,271 @@ description: >-
3838

3939
# Team tokens API reference
4040

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

43299
## Generate a new team token
44300

45301
Generates a new team token and overrides existing token if one exists.
46302

47303
| Method | Path |
48304
| :----- | :----------------------------------- |
49-
| POST | /teams/:team_id/authentication-token |
305+
| POST | /teams/:team_id/authentication-tokens |
50306

51307
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.
52308

@@ -62,6 +318,7 @@ This POST endpoint requires a JSON object with the following properties as a req
62318
| Key path | Type | Default | Description |
63319
| ----------------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------- |
64320
| `data.type` | string | | Must be `"authentication-token"`. |
321+
| `data.attributes.description` | string | `null` | The description of the team token, if supplied, otherwise the description will be `null`. The description **must** be unique within the context of the team, meaning legacy tokens may only have one `null` or one descriptive description at a time. |
65322
| `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. |
66323

67324
### Sample payload
@@ -85,7 +342,7 @@ curl \
85342
--header "Content-Type: application/vnd.api+json" \
86343
--request POST \
87344
--data @payload.json \
88-
https://app.terraform.io/api/v2/teams/team-BUHBEM97xboT8TVz/authentication-token
345+
https://app.terraform.io/api/v2/teams/team-BUHBEM97xboT8TVz/authentication-tokens
89346
```
90347

91348
### Sample response
@@ -234,19 +491,19 @@ This endpoint supports pagination [with standard URL query parameters](/terrafor
234491

235492
Use this endpoint to display a [team token](/terraform/cloud-docs/users-teams-organizations/teams#api-tokens) for a particular team.
236493

237-
`GET /teams/:team-id/authentication-token`
494+
`GET /teams/:team_id/authentication-token`
238495

239496
| Parameter | Description |
240497
| ---------- | ------------------------- |
241-
| `:team-id` | The ID of the Team. |
498+
| `:team_id` | The ID of the Team. |
242499

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

245-
`GET /authentication-tokens/:token-id`
502+
`GET /authentication-tokens/:token_id`
246503

247504
| Parameter | Description |
248505
| ----------- | ------------------------- |
249-
| `:token-id` | The ID of the Team Token. |
506+
| `:token_id` | The ID of the Team Token. |
250507

251508
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.
252509

@@ -296,4 +553,3 @@ curl \
296553
}
297554
}
298555
```
299-

‎website/docs/cloud-docs/users-teams-organizations/api-tokens.mdx

+4-2
Original file line numberDiff line numberDiff line change
@@ -14,15 +14,17 @@ Refer to [Team Token API](/terraform/cloud-docs/api-docs/team-tokens) and [Organ
1414

1515
## User API Tokens
1616

17-
API tokens may belong directly to a user. User tokens are the most flexible token type because they inherit permissions from the user they are associated with. For more information on user tokens and how to generate them, see the [Users](/terraform/cloud-docs/users-teams-organizations/users#api-tokens) documentation.
17+
API tokens may belong directly to a user. User tokens are the most flexible token type because they inherit permissions from the user they are associated with. For more information on user tokens and how to generate them, see the [Users](/terraform/cloud-docs/users-teams-organizations/users#tokens) documentation.
1818

1919
## Team API Tokens
2020

2121
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.
2222

2323
Navigate to the **Organization settings > API Tokens > Team Token** tab to manage API tokens for a team or create new team tokens.
2424

25-
Each team can have **one** valid API token at a time. When a token is regenerated, the previous token immediately becomes invalid.
25+
Each team can have multiple, valid API tokens at a time, unless the team is using the legacy team token API.
26+
27+
For teams relying on the [**legacy**](/terraform/cloud-docs/api-docs/team-tokens#legacy-team-tokens-api-reference) team token API, each team can only have **one** valid API token at a time. When a legacy team token is generated, the previous token immediately becomes invalid.
2628

2729
Owners and users with [manage teams](/terraform/cloud-docs/users-teams-organizations/permissions#manage-teams) permissions have the ability to enable and disable team token management for a team, which limits the actions that team members can take on a team token. Refer to [Allow Member Token Management](/terraform/cloud-docs/users-teams-organizations/permissions#allow-member-token-management) for more information.
2830

‎website/docs/cloud-docs/users-teams-organizations/permissions.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -331,7 +331,7 @@ In order to remove a user from the organization, the holder of this permission m
331331

332332
#### Manage Teams
333333

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

336336
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.
337337

0 commit comments

Comments
 (0)