Terraform
Team token API
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 to null 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-token
Sample 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-token
List team tokens
Lists the team 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 | Empty JSON API document | The specified organization has no team tokens. |
| 404 | JSON API error object | Organization not found. |
Query parameters
This endpoint supports pagination with standard URL 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 "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 a team 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 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 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-token
Sample 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"
}
}
}
}
}