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.
Generate a new team token
Generates a new team token and overrides existing token if one exists.
| Method | Path |
|---|---|
| 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.
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-token". | |
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 tonull the token will never expire. |
Sample payload
{ "data": { "type": "authentication-token", "attributes": { "expired-at": "2023-04-06T12:00:00.000Z" } }}Sample request
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-tokenSample response
{ "data": { "id": "4111797", "type": "authentication-tokens", "attributes": { "created-at": "2017-11-29T19:18:09.976Z", "last-used-at": null, "description": null, "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 the team token
| Method | Path |
|---|---|
| DELETE | /teams/:team_id/authentication-token |
Parameters
:team_id(string: <required>) - specifies the team_id from which to delete the token
Sample request
curl \ --header "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/vnd.api+json" \ --request DELETE \ https://app.terraform.io/api/v2/teams/team-BUHBEM97xboT8TVz/authentication-tokenList team tokens
Lists theteam tokens in an organization.
GET organizations/:organization_name/team-tokens
| Parameter | Description |
|---|---|
: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.
By default, this endpoint returns tokens by ascending expiration date.
| Status | Response | Reason |
|---|---|---|
| 200 | JSON API document (type: "team-tokens") | The request was successful. |
| 200 | EmptyJSON API document | The specified organization has no team tokens. |
| 404 | JSON API error object | Organization not found. |
Query parameters
This endpoint supports paginationwith standard URL query parameters and searching with theq 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"team-name","created-by","expired-at", and"last-used-at". Prepending a hyphen to the sort parameter reverses the order. For example,"-team-name" sorts by name in reverse alphabetical order. If omitted, the default sort order ascending. |
Sample response
{ "data": [ { "id": "at-TLhN8cc6ro6qYDvp", "type": "authentication-tokens", "attributes": { "created-at": "2024-06-19T18:28:25.267Z", "last-used-at": null, "description": null, "token": null, "expired-at": "2024-07-19T18:28:25.030Z" }, "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": null, "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 ateam token 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 theauthentication-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 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
curl \ --header "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/vnd.api+json" \ --request GET \ https://app.terraform.io/api/v2/teams/team-6yEmxNAhaoQLH1Da/authentication-tokenSample response
{ "data": { "id": "at-6yEmxNAhaoQLH1Da", "type": "authentication-tokens", "attributes": { "created-at": "2023-11-25T22:31:30.624Z", "last-used-at": "2023-11-26T20:34:59.487Z", "description": null, "token": null, "expired-at": "2024-04-06T12:00:00.000Z" }, "relationships": { "team": { "data": { "id": "team-LnREdjodkvZFGdXL", "type": "teams" } }, "created-by": { "data": { "id": "user-MA4GL63FmYRpSFxa", "type": "users" } } } }}