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

You are viewing documentation for version v202212-2. View latest version.

User Tokens API

List User Tokens

GET /users/:user_id/authentication-tokens

ParameterDescription
:user_idThe ID of the User.

Use the Account API to find your own user ID.

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.

Note: You must access this endpoint with a user token, and it will only return useful data for that token's user account.

StatusResponseReason
200JSON API document (type: "authentication-tokens")The request was successful
200Empty JSON API document (no type)User has no authentication tokens, or request was made by someone other than the user
404JSON API error objectUser not found

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. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results.

ParameterDescription
page[number]Optional. If omitted, the endpoint will return the first page.
page[size]Optional. If omitted, the endpoint will return 20 user 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/users/user-MA4GL63FmYRpSFxa/authentication-tokens

Sample Response

{
  "data": [
    {
      "id": "at-QmATJea6aWj1xR2t",
      "type": "authentication-tokens",
      "attributes": {
        "created-at": "2018-11-06T22:56:10.203Z",
        "last-used-at": null,
        "description": null,
        "token": null
      },
      "relationships": {
        "created-by": {
          "data": null
        }
      }
    },
    {
      "id": "at-6yEmxNAhaoQLH1Da",
      "type": "authentication-tokens",
      "attributes": {
        "created-at": "2018-11-25T22:31:30.624Z",
        "last-used-at": "2018-11-26T20:27:54.931Z",
        "description": "api",
        "token": null
      },
      "relationships": {
        "created-by": {
          "data": {
            "id": "user-MA4GL63FmYRpSFxa",
            "type": "users"
          }
        }
      }
    }
  ]
}

Show a User Token

GET /authentication-tokens/:id

ParameterDescription
:idThe ID of the User Token.

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.

Note: You must access this endpoint with a user token, and it will only return useful data for that token's user account.

StatusResponseReason
200JSON API document (type: "authentication-tokens")The request was successful
404JSON API error objectUser Token not found, or unauthorized to view the User Token

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-6yEmxNAhaoQLH1Da

Sample Response

{
  "data": {
    "id": "at-6yEmxNAhaoQLH1Da",
    "type": "authentication-tokens",
    "attributes": {
      "created-at": "2018-11-25T22:31:30.624Z",
      "last-used-at": "2018-11-26T20:34:59.487Z",
      "description": "api",
      "token": null
    },
    "relationships": {
      "created-by": {
        "data": {
          "id": "user-MA4GL63FmYRpSFxa",
          "type": "users"
        }
      }
    }
  }
}

Create a User Token

POST /users/:user_id/authentication-tokens

ParameterDescription
:user_idThe ID of the User.

Use the Account API to find your own user ID.

This endpoint returns the secret text of the created authentication token. A token is only shown upon creation, and cannot be recovered later.

Note: You must access this endpoint with a user token, and it will only create new tokens for that token's user account.

StatusResponseReason
201JSON API document (type: "authentication-tokens")The request was successful
404JSON API error objectUser not found or user unauthorized to perform action
422JSON API error objectMalformed request body (missing attributes, wrong types, etc.)
500JSON API error objectFailure during User 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 pathTypeDefaultDescription
data.typestringMust be "authentication-tokens".
data.attributes.descriptionstringThe description for the User 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/users/user-MA4GL63FmYRpSFxa/authentication-tokens

Sample Response

{
  "data": {
    "id": "at-MKD1X3i4HS3AuD41",
    "type": "authentication-tokens",
    "attributes": {
      "created-at": "2018-11-26T20:48:35.054Z",
      "last-used-at": null,
      "description": "api",
      "token": "6tL24nM38M7XWQ.atlasv1.KmWckRfzeNmUVFNvpvwUEChKaLGznCSD6fPf3VPzqMMVzmSxFU0p2Ibzpo2h5eTGwPU"
    },
    "relationships": {
      "created-by": {
        "data": {
          "id": "user-MA4GL63FmYRpSFxa",
          "type": "users"
        }
      }
    }
  }
}

Destroy a User Token

DELETE /authentication-tokens/:id

ParameterDescription
:idThe ID of the User Token to destroy.

Note: You must access this endpoint with a user token, and it will only delete tokens for that token's user account.

StatusResponseReason
204Empty responseThe User Token was successfully destroyed
404JSON API error objectUser 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