Add API Documentation for Multi-Team Tokens #875
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,7 +1,7 @@ | ||
| --- | ||
| page_title: /teams/:team_id/authentication-tokens API reference for HCP Terraform | ||
| description: >- | ||
| 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. 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: <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"`. | | ||
|
There was a problem hiding this comment. Updated this to be the plural |
||
| | `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", | ||
|
There was a problem hiding this comment. Updated this to be the plural |
||
| "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 | | ||
| | :----- | :----------------------------------- | | ||
juliannatetreault marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | 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/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 | ||
juliannatetreault marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| { | ||
| "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. | ||
juliannatetreault marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| | 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 | ||
juliannatetreault marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
juliannatetreault marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| 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 | | ||
juliannatetreault marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| 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. | ||
juliannatetreault marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ### 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` | ||
|
|
||
| | Parameter | Description | | ||
| | ---------- | ------------------------- | | ||
| | `: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` | ||
|
|
||
| | 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 text is only shown upon creation, and cannot be recovered later. | ||
|
|
||
| | Status | Response | Reason | | ||
| | ------- | ------------------------------------------------------- | ------------------------------------------------------------ | | ||
|
|
@@ -296,4 +556,3 @@ curl \ | |
| } | ||
| } | ||
| ``` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.