User tokens API reference

List User Tokens

GET /users/:user_id/authentication-tokens

Parameter	Description
`:user_id`	The 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.

Status	Response	Reason
200	JSON API document (`type: "authentication-tokens"`)	The request was successful
200	Empty JSON API document (no type)	User has no authentication tokens, or request was made by someone other than the user
404	JSON API error object	User 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.

Parameter	Description
`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,
        "expired-at": 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,
        "expired-at": "2023-04-06T12:00:00.000Z"
      },
      "relationships": {
        "created-by": {
          "data": {
            "id": "user-MA4GL63FmYRpSFxa",
            "type": "users"
          }
        }
      }
    }
  ]
}

Show a User Token

GET /authentication-tokens/:id

Parameter	Description
`:id`	The 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.

Status	Response	Reason
200	JSON API document (`type: "authentication-tokens"`)	The request was successful
404	JSON API error object	User 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,
      "expired-at": "2023-04-06T12:00:00.000Z"
    },
    "relationships": {
      "created-by": {
        "data": {
          "id": "user-MA4GL63FmYRpSFxa",
          "type": "users"
        }
      }
    }
  }
}

Create a User Token

POST /users/:user_id/authentication-tokens

Parameter	Description
`:user_id`	The 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.

Status	Response	Reason
201	JSON API document (`type: "authentication-tokens"`)	The request was successful
404	JSON API error object	User 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 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 path	Type	Default	Description
`data.type`	string		Must be `"authentication-tokens"`.
`data.attributes.description`	string		The description for the User Token.
`data.attributes.expired-at`	string	`null`	The UTC date and time that the User Token will expire in ISO 8601 format. If omitted or set to `null`, the token will expire two years from the date of creation.

Sample Payload

{
  "data": {
    "type": "authentication-tokens",
    "attributes": {
      "description":"api",
      "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/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",
      "expired-at": "2023-04-06T12:00:00.000Z"
    },
    "relationships": {
      "created-by": {
        "data": {
          "id": "user-MA4GL63FmYRpSFxa",
          "type": "users"
        }
      }
    }
  }
}

Destroy a User Token

DELETE /authentication-tokens/:id

Parameter	Description
`:id`	The 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.

Status	Response	Reason
204	Empty response	The User Token was successfully destroyed
404	JSON API error object	User 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