» 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