HashiCorp Developer AI Private beta now available Sign up today
Terraform
Terraform Home

You are viewing documentation for version v202409-1. View latest version.

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.

MethodPath
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 pathTypeDefaultDescription
data.typestringMust be "authentication-token".
data.attributes.expired-atstringnullThe 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

MethodPath
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

ParameterDescription
:organization_nameThe 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.

StatusResponseReason
200JSON API document (type: "team-tokens")The request was successful.
200Empty JSON API documentThe specified organization has no team tokens.
404JSON API error objectOrganization 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.

ParameterDescription
page[number]Optional. If omitted, the endpoint returns the first page.
page[size]Optional. If omitted, the endpoint returns 20 tokens per page.
qOptional. A search query string. You can search for a team authentication token using the team name.
sortOptional. 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

ParameterDescription
:team-idThe 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

ParameterDescription
:token-idThe 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.

StatusResponseReason
200JSON API document (type: "authentication-tokens")The request was successful
404JSON API error objectTeam 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"
        }
      }
    }
  }
}