Admin user tokens API

The admin/user-tokens API lets site administrators list and delete user API tokens across all users in a Terraform Enterprise installation. Only admins and operators who install and maintain their organization's Terraform Enterprise instance can use admin API endpoints.

List all user tokens

GET /api/v2/admin/user-tokens

This endpoint lists all user API tokens across all users in the Terraform Enterprise installation.

Query Parameters

These are standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  "https://<TFE_HOSTNAME>/api/v2/admin/user-tokens"

Sample Request with Filters

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  "https://<TFE_HOSTNAME>/api/v2/admin/user-tokens?filter%5Bexpiry_status%5D=expired,expiring_in_7_days&sort=-expired-at"

Sample Response

{
  "data": [
    {
      "id": "at-QoKZi25LmA1RDfzR",
      "type": "authentication-tokens",
      "attributes": {
        "created-at": "2024-01-15T12:00:00.000Z",
        "last-used-at": "2024-06-01T08:30:00.000Z",
        "description": "CI pipeline token",
        "expired-at": "2025-01-15T12:00:00.000Z",
        "expiry-status": "expired"
      },
      "relationships": {
        "created-by": {
          "data": {
            "id": "user-ZL4MsEKnd6iTigTb",
            "type": "users"
          }
        }
      }
    }
  ],
  "links": {
    "self": "https://<TFE_HOSTNAME>/api/v2/admin/user-tokens?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://<TFE_HOSTNAME>/api/v2/admin/user-tokens?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://<TFE_HOSTNAME>/api/v2/admin/user-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
    }
  }
}

Delete a user token

DELETE /api/v2/admin/user-tokens/:token_id

This endpoint deletes a single user API token.

Administrators cannot delete their own token using this endpoint. Self-deletion is blocked. Use the user tokens API to manage your own tokens.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  "https://<TFE_HOSTNAME>/api/v2/admin/user-tokens/at-QoKZi25LmA1RDfzR"

Bulk-delete user tokens

DELETE /api/v2/admin/user-tokens

This endpoint deletes up to 100 user API tokens in a single atomic operation. If the call fails to delete all tokens in the request, Terraform Enterprise doesn't delete any of the tokens. Instead, it aborts the operation so that the system doesn't enter an inconsistent state.

The maximum number of tokens you can delete in a single request is 100. Terraform Enterprise rejects requests that specify more than 100 token IDs. Self-deletion is blocked, so administrators cannot include their own token in a bulk delete request. Instead, use the user tokens API to manage your own tokens.

Request Body

To send a DELETE request, you must include a JSON object with the following properties as a request payload.

Sample Payload

{
  "data": [
    {
      "type": "authentication-tokens",
      "id": "at-QoKZi25LmA1RDfzR"
    },
    {
      "type": "authentication-tokens",
      "id": "at-Ry7nKpL3bXwTmJ9Q"
    }
  ]
}

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  --data @payload.json \
  "https://<TFE_HOSTNAME>/api/v2/admin/user-tokens"