diff --git a/website/docs/cloud-docs/api-docs/changelog.mdx b/website/docs/cloud-docs/api-docs/changelog.mdx index 3a16ca459..10dc16363 100644 --- a/website/docs/cloud-docs/api-docs/changelog.mdx +++ b/website/docs/cloud-docs/api-docs/changelog.mdx @@ -9,6 +9,10 @@ description: >- Keep track of changes to the API for HCP Terraform and Terraform Enterprise. +## 2025-03-20 +* Add API documentation for multiple [team tokens](/terraform/cloud-docs/api-docs/api-tokens), and update documentation around [legacy team tokens](/terraform/cloud-docs/api-docs/team-tokens##legacy-team-tokens-api-reference). +* Update existing API documentation for [team tokens](/terraform/cloud-docs/api-docs/team-tokens) to distinguish multiple team tokens from [legacy team tokens](/terraform/cloud-docs/api-docs/team-tokens##legacy-team-tokens-api-reference). + ## 2025-3-10 * Document unique pagination metadata given in the response of [Organization Runs Index API](/terraform/cloud-docs/api-docs/run##list-runs-in-an-organization). diff --git a/website/docs/cloud-docs/api-docs/team-tokens.mdx b/website/docs/cloud-docs/api-docs/team-tokens.mdx index 2c204bbda..6d745e2c5 100644 --- a/website/docs/cloud-docs/api-docs/team-tokens.mdx +++ b/website/docs/cloud-docs/api-docs/team-tokens.mdx @@ -1,7 +1,7 @@ --- -page_title: /teams/authentication-token API reference for HCP Terraform +page_title: /teams/:team_id/authentication-tokens API reference for HCP Terraform description: >- - Use the HCP Terraform API's `/teams/authentication-token` endpoint to generate, delete, and list a team's API tokens. + Use the HCP Terraform API's `/teams/:team_id/authentication-tokens` endpoint to generate, delete, and list a team's API tokens. --- [200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 @@ -38,7 +38,267 @@ description: >- # Team tokens API reference -Team API tokens grant access to a team's workspaces. Each team can have an API token that is not associated with a specific user. You can create and delete team tokens and list an organization's team tokens. +Team API tokens grant access to a team's workspaces. Teams are not limited to a single token, and can have multiple tokens at a time. Team tokens are not associated with a specific user. + +Teams relying on the [**legacy**](/terraform/cloud-docs/api-docs/team-tokens#legacy-team-tokens-api-reference) team token API (`/teams/: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/cloud-docs/api-docs#query-parameters) and searching with the `q` parameter. Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +|----------------|---------------------------------------------------------------------| +| `page[number]` | **Optional.** If omitted, the endpoint returns the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint returns 20 tokens per page. | +| `q` | **Optional.** A search query string. You can search for a team authentication token using the team name. | +| `sort` | **Optional.** Allows sorting the team tokens by `"created-by"`, `"expired-at"`, and `"last-used-at"`. Prepending a hyphen to the sort parameter reverses the order. If omitted, the default sort order ascending. | + +### Sample response + +```json +{ + "data": [ + { + "id": "at-TLhN8cc6ro6qYDvp", + "type": "authentication-tokens", + "attributes": { + "created-at": "2017-11-29T19:18:09.976Z", + "last-used-at": null, + "description": "Team API token for team ABC", + "token": "QnbSxjjhVMHJgw.atlasv1.gxZnWIjI5j752DGqdwEUVLOFf0mtyaQ00H9bA1j90qWb254lEkQyOdfqqcq9zZL7Sm0", + "expired-at": "2023-04-06T12:00:00.000Z" + }, + "relationships": { + "team": { + "data": { + "id": "team-Y7RyjccPVBKVEdp7", + "type": "teams" + } + }, + "created-by": { + "data": { + "id": "user-ccU6h629sszLJBpY", + "type": "users" + } + } + } + }, + { + "id": "at-qfc2wqqJ1T5sCamM", + "type": "authentication-tokens", + "attributes": { + "created-at": "2024-06-19T18:44:44.051Z", + "last-used-at": null, + "description": "Team API token for team XYZ", + "token": null, + "expired-at": "2024-07-19T18:44:43.818Z" + }, + "relationships": { + "team": { + "data": { + "id": "team-58pFiBffTLMxLphR", + "type": "teams" + } + }, + "created-by": { + "data": { + "id": "user-ccU6h629hhzLJBpY", + "type": "users" + } + } + } + }, + ] +} +``` + +## Show a team token + +Use this endpoint to display a particular [team token](/terraform/cloud-docs/users-teams-organizations/teams#api-tokens). + +`GET /authentication-tokens/:token_id` + +| Parameter | Description | +| ----------- | ------------------------- | +| `:token_id` | The ID of the Team Token. | + +The object returned by this endpoint only contains metadata, and does not include the secret text of the authentication token. A token's secret test is only shown upon creation, and cannot be recovered later. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "authentication-tokens"`) | The request was successful | +| [404][] | [JSON API error object][] | Team Token not found, or unauthorized to view the Team Token | + +### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/authentication-tokens/at-6yEmxNAhaoQLH1Da +``` + +### Sample response + +```json +{ + "data": { + "id": "at-6yEmxNAhaoQLH1Da", + "type": "authentication-tokens", + "attributes": { + "created-at": "2017-11-29T19:18:09.976Z", + "last-used-at": null, + "description": "Team API token for team ABC", + "token": "QnbSxjjhVMHJgw.atlasv1.gxZnWIjI5j752DGqdwEUVLOFf0mtyaQ00H9bA1j90qWb254lEkQyOdfqqcq9zZL7Sm0", + "expired-at": "2023-04-06T12:00:00.000Z" + }, + "relationships": { + "team": { + "data": { + "id": "team-LnREdjodkvZFGdXL", + "type": "teams" + } + }, + "created-by": { + "data": { + "id": "user-MA4GL63FmYRpSFxa", + "type": "users" + } + } + } + } +} +``` + +# Legacy team tokens API reference + +Legacy team API tokens grant access to a team's workspaces. Each team can have a single legacy API token that is not associated with a specific user. +You can create and delete team tokens and list an organization's team tokens. +The [team tokens API](/terraform/cloud-docs/api-docs/team-tokens) includes the same functionality as legacy team tokens, and allows you to provision multiple tokens with descriptions per team. ## Generate a new team token @@ -48,7 +308,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 this token when you create it and can not recover it later. +This endpoint returns the secret text of the new authentication token. You can only access the secret when you create it and cannot recover it later. ### Parameters @@ -234,21 +494,21 @@ This endpoint supports pagination [with standard URL query parameters](/terrafor Use this endpoint to display a [team token](/terraform/cloud-docs/users-teams-organizations/teams#api-tokens) for a particular team. -`GET /teams/:team-id/authentication-token` +`GET /teams/:team_id/authentication-token` | Parameter | Description | | ---------- | ------------------------- | -| `:team-id` | The ID of the Team. | +| `:team_id` | The ID of the Team. | You can also fetch a team token directly by using the token's ID with the `authentication-tokens/` endpoint. -`GET /authentication-tokens/:token-id` +`GET /authentication-tokens/:token_id` | Parameter | Description | | ----------- | ------------------------- | -| `:token-id` | The ID of the Team Token. | +| `:token_id` | The ID of the Team Token. | -The object returned by this endpoint only contains metadata, and does not include the secret text of the authentication token. A token's secret test is only shown upon creation, and cannot be recovered later. +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 | | ------- | ------------------------------------------------------- | ------------------------------------------------------------ | @@ -296,4 +556,3 @@ curl \ } } ``` - diff --git a/website/docs/cloud-docs/users-teams-organizations/api-tokens.mdx b/website/docs/cloud-docs/users-teams-organizations/api-tokens.mdx index c4a5787d1..ffaec40f6 100644 --- a/website/docs/cloud-docs/users-teams-organizations/api-tokens.mdx +++ b/website/docs/cloud-docs/users-teams-organizations/api-tokens.mdx @@ -14,15 +14,19 @@ Refer to [Team Token API](/terraform/cloud-docs/api-docs/team-tokens) and [Organ ## User API Tokens -API tokens may belong directly to a user. User tokens are the most flexible token type because they inherit permissions from the user they are associated with. For more information on user tokens and how to generate them, see the [Users](/terraform/cloud-docs/users-teams-organizations/users#api-tokens) documentation. +API tokens may belong directly to a user. User tokens are the most flexible token type because they inherit permissions from the user they are associated with. For more information on user tokens and how to generate them, see the [Users](/terraform/cloud-docs/users-teams-organizations/users#tokens) documentation. ## Team API Tokens API tokens may belong to a specific team. Team API tokens allow access to the workspaces that the team has access to, without being tied to any specific user. -Navigate to the **Organization settings > API Tokens > Team Token** tab to manage API tokens for a team or create new team tokens. +Navigate to the **Organization Settings > API Tokens > Team Tokens** tab to manage API tokens for a team or create new team tokens. -Each team can have **one** valid API token at a time. When a token is regenerated, the previous token immediately becomes invalid. +Teams can have multiple valid tokens at a time, so long as the tokens' descriptions are unique within the context of the given team. A token without a description is considered a legacy token, and only one legacy token can exist at a given time. + +The [**legacy API**](/terraform/cloud-docs/api-docs/team-tokens#legacy-team-tokens-api-reference) will only operate on the legacy token, and generating a new legacy token invalidates the previous legacy token. + +The [**non-legacy API**](/terraform/cloud-docs/api-docs/team-tokens#team-tokens-api-reference) will support the existence of multiple, valid team tokens, meaning that when a new, non-legacy token is generated, existing tokens will remain valid. Owners and users with [manage teams](/terraform/cloud-docs/users-teams-organizations/permissions#manage-teams) permissions have the ability to enable and disable team token management for a team, which limits the actions that team members can take on a team token. Refer to [Allow Member Token Management](/terraform/cloud-docs/users-teams-organizations/permissions#allow-member-token-management) for more information. diff --git a/website/docs/cloud-docs/users-teams-organizations/permissions.mdx b/website/docs/cloud-docs/users-teams-organizations/permissions.mdx index 5358f0919..5b37ee0ca 100644 --- a/website/docs/cloud-docs/users-teams-organizations/permissions.mdx +++ b/website/docs/cloud-docs/users-teams-organizations/permissions.mdx @@ -331,7 +331,7 @@ In order to remove a user from the organization, the holder of this permission m #### Manage Teams -Allows members to create, update, and delete teams, and generate, regenerate, and revoke tokens. +Allows members to create, update, and delete teams, and generate, and revoke tokens. This permission grants the ability to update a team's names, SSO IDs, and token management permissions, but does not allow access to organization settings. On its own, this permission does not allow users to create, update, delete, or otherwise access secret teams.