A new platform for documentation and tutorials is launching soon.
We are migrating Terraform documentation into HashiCorp Developer, our new developer experience.
Search Terraform documentation » Agent Tokens APINote: Terraform Cloud Agents are a paid feature, available as part of the Terraform Cloud for Business upgrade package. Learn more about Terraform Cloud pricing here .
» List Agent TokensGET /agent-pools/:agent_pool_id/authentication-tokens
Parameter Description :agent_pool_id
The ID of the Agent Pool.
The objects returned by this endpoint only contain metadata, and do not include the secret text of any authentication tokens. A token is only shown upon creation, and cannot be recovered later.
» Query ParametersThis endpoint supports pagination with standard URL query parameters . 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 will return the first page.page[size]
Optional. If omitted, the endpoint will return 20 tokens per page.
» Sample Requestcurl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd/authentication-tokens
curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd/authentication-tokens
» Sample Response{
"data" : [
{
"id" : "at-bonpPzYqv2bGD7vr" ,
"type" : "authentication-tokens" ,
"attributes" : {
"created-at" : "2020-08-07T19:38:20.868Z" ,
"last-used-at" : "2020-08-07T19:40:55.139Z" ,
"description" : "asdfsdf" ,
"token" : null
} ,
"relationships" : {
"created-by" : {
"data" : {
"id" : "user-Nxv6svuhVrTW7eb1" ,
"type" : "users"
}
}
}
}
] ,
"links" : {
"self" : "https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd/authentication-tokens?page%5Bnumber%5D=1&page%5Bsize%5D=20" ,
"first" : "https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd/authentication-tokens?page%5Bnumber%5D=1&page%5Bsize%5D=20" ,
"prev" : null ,
"next" : null ,
"last" : "https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd/authentication-tokens?page%5Bnumber%5D=1&page%5Bsize%5D=20"
} ,
"meta" : {
"pagination" : {
"current-page" : 1 ,
"prev-page" : null ,
"next-page" : null ,
"total-pages" : 1 ,
"total-count" : 1
}
}
}
{
"data" : [
{
"id" : "at-bonpPzYqv2bGD7vr" ,
"type" : "authentication-tokens" ,
"attributes" : {
"created-at" : "2020-08-07T19:38:20.868Z" ,
"last-used-at" : "2020-08-07T19:40:55.139Z" ,
"description" : "asdfsdf" ,
"token" : null
} ,
"relationships" : {
"created-by" : {
"data" : {
"id" : "user-Nxv6svuhVrTW7eb1" ,
"type" : "users"
}
}
}
}
] ,
"links" : {
"self" : "https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd/authentication-tokens?page%5Bnumber%5D=1&page%5Bsize%5D=20" ,
"first" : "https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd/authentication-tokens?page%5Bnumber%5D=1&page%5Bsize%5D=20" ,
"prev" : null ,
"next" : null ,
"last" : "https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd/authentication-tokens?page%5Bnumber%5D=1&page%5Bsize%5D=20"
} ,
"meta" : {
"pagination" : {
"current-page" : 1 ,
"prev-page" : null ,
"next-page" : null ,
"total-pages" : 1 ,
"total-count" : 1
}
}
}
» Show an Agent TokenGET /authentication-tokens/:id
Parameter Description :id
The ID of the Agent Token to show
» Sample Requestcurl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/authentication-tokens/at-bonpPzYqv2bGD7vr
curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/authentication-tokens/at-bonpPzYqv2bGD7vr
» Sample Response{
"data" : {
"id" : "at-bonpPzYqv2bGD7vr" ,
"type" : "authentication-tokens" ,
"attributes" : {
"created-at" : "2020-08-07T19:38:20.868Z" ,
"last-used-at" : "2020-08-07T19:40:55.139Z" ,
"description" : "test token" ,
"token" : null
} ,
"relationships" : {
"created-by" : {
"data" : {
"id" : "user-Nxv6svuhVrTW7eb1" ,
"type" : "users"
}
}
}
}
}
{
"data" : {
"id" : "at-bonpPzYqv2bGD7vr" ,
"type" : "authentication-tokens" ,
"attributes" : {
"created-at" : "2020-08-07T19:38:20.868Z" ,
"last-used-at" : "2020-08-07T19:40:55.139Z" ,
"description" : "test token" ,
"token" : null
} ,
"relationships" : {
"created-by" : {
"data" : {
"id" : "user-Nxv6svuhVrTW7eb1" ,
"type" : "users"
}
}
}
}
}
» Create an Agent TokenPOST /agent-pools/:agent_pool_id/authentication-tokens
Parameter Description :agent_pool_id
The ID of the Agent Pool
This endpoint returns the secret text of the created authentication token. A token is only shown upon creation, and cannot be recovered later.
» Request BodyThis POST endpoint requires a JSON object with the following properties as a request payload.
Properties without a default value are required.
Key path Type Default Description data.type
string Must be "authentication-tokens"
. data.attributes.description
string The description for the Agent Token.
» Sample Payload{
"data" : {
"type" : "authentication-tokens" ,
"attributes" : {
"description" : "api"
}
}
}
{
"data" : {
"type" : "authentication-tokens" ,
"attributes" : {
"description" : "api"
}
}
}
» Sample Requestcurl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request POST \
--data @payload.json \
https://app.terraform.io/api/v2/agent-pools/apool-xkuMi7x4LsEnBUdY/authentication-tokens
curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request POST \
--data @payload.json \
https://app.terraform.io/api/v2/agent-pools/apool-xkuMi7x4LsEnBUdY/authentication-tokens
» Sample Response{
"data" : {
"id" : "at-2rG2oYU9JEvfaqji" ,
"type" : "authentication-tokens" ,
"attributes" : {
"created-at" : "2020-08-10T22:29:21.907Z" ,
"last-used-at" : null ,
"description" : "api" ,
"token" : "eHub7TsW7fz7LQ.atlasv1.cHGFcvf2VxVfUH4PZ7UNdaGB6SjyKWs5phdZ371zkI2KniZs2qKgrAcazhlsiy02awk"
} ,
"relationships" : {
"created-by" : {
"data" : {
"id" : "user-Nxv6svuhVrTW7eb1" ,
"type" : "users"
}
}
}
}
}
{
"data" : {
"id" : "at-2rG2oYU9JEvfaqji" ,
"type" : "authentication-tokens" ,
"attributes" : {
"created-at" : "2020-08-10T22:29:21.907Z" ,
"last-used-at" : null ,
"description" : "api" ,
"token" : "eHub7TsW7fz7LQ.atlasv1.cHGFcvf2VxVfUH4PZ7UNdaGB6SjyKWs5phdZ371zkI2KniZs2qKgrAcazhlsiy02awk"
} ,
"relationships" : {
"created-by" : {
"data" : {
"id" : "user-Nxv6svuhVrTW7eb1" ,
"type" : "users"
}
}
}
}
}
» Destroy an Agent TokenDELETE /api/v2/authentication-tokens/:id
Parameter Description :id
The ID of the Agent Token to destroy.
Status Response Reason 204 Empty response The Agent Token was successfully destroyed 404 JSON API error object Agent Token not found, or user unauthorized to perform action
» Sample Requestcurl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request DELETE \
https://app.terraform.io/api/v2/authentication-tokens/at-6yEmxNAhaoQLH1Da
curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request DELETE \
https://app.terraform.io/api/v2/authentication-tokens/at-6yEmxNAhaoQLH1Da