Terraform
Agent Tokens API
List Agent Tokens
GET /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.
| Status | Response | Reason |
|---|---|---|
| 200 | JSON API document (type: "authentication-tokens") | Success |
| 404 | JSON API error object | Agent Pool not found, or user unauthorized to perform action |
Query Parameters
This 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 Request
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
}
}
}
Show an Agent Token
GET /authentication-tokens/:id
| Parameter | Description |
|---|---|
:id | The ID of the Agent Token to show |
| Status | Response | Reason |
|---|---|---|
| 200 | JSON API document (type: "authentication-tokens") | Success |
| 404 | JSON API error object | Agent Token not found, or user unauthorized to perform action |
Sample Request
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"
}
}
}
}
}
Create an Agent Token
POST /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.
| Status | Response | Reason |
|---|---|---|
| 201 | JSON API document (type: "authentication-tokens") | The request was successful |
| 404 | JSON API error object | Agent Pool not found or user unauthorized to perform action |
| 422 | JSON API error object | Malformed request body (missing attributes, wrong types, etc.) |
| 500 | JSON API error object | Failure during Agent Token creation |
Request Body
This 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"
}
}
}
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/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"
}
}
}
}
}
Destroy an Agent Token
DELETE /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 Request
curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request DELETE \
https://app.terraform.io/api/v2/authentication-tokens/at-6yEmxNAhaoQLH1Da