How-to check API token permissions for Terraform Enterprise or HCP Terraform

Introduction

In Terraform Enterprise or HCP Terraform, you can generate API tokens at several levels:

• User token
• Team token
• Organization token

The actions available to a token depend on its type and the permissions assigned to the user or team for which it was generated. This guide provides a method to inspect the permissions associated with a given API token.

Prerequisites

• A User, Team, or Organization API token for your Terraform Enterprise or HCP Terraform instance.
• The hostname of your Terraform Enterprise instance or app.terraform.io for HCP Terraform.
• The name of the organization you wish to query.
• (Optional) The jq command-line tool to format the JSON output. For installation instructions, refer to the jq official website.

Procedure

Use the API token to query the organization details endpoint. The response body includes an object detailing the permissions associated with the token.

More details about the API are available in the Show an Organization API documentation.

Execute the following command, replacing the placeholder values with your information. For HCP Terraform, use app.terraform.io as the hostname.

## Replace placeholder values before running
export TOKEN="<YOUR_API_TOKEN>"
export TFE_HOSTNAME="<YOUR_TFE_HOSTNAME>"
export TFE_ORG_NAME="<YOUR_ORGANIZATION_NAME>"

curl \
  --silent \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://$TFE_HOSTNAME/api/v2/organizations/$TFE_ORG_NAME | jq '.data.attributes.permissions'

Example Output

The command returns a JSON object that lists the token's permissions.

{
  "can-update": true,
  "can-update-authentication": true,
  "can-destroy": true,
  "can-access-via-teams": true,
  "can-create-module": true,
  "can-create-team": true,
  "can-create-workspace": true,
  "can-manage-users": true,
  "can-manage-subscription": true,
  "can-view-subscription": true,
  "can-manage-sso": true,
  "can-update-oauth": true,
  "can-update-sentinel": true,
  "can-update-ssh-keys": true,
  "can-update-api-token": true,
  "can-traverse": true,
  "can-view-usage": true,
  "can-update-agent-pools": true,
  "can-manage-tags": true,
  "can-manage-varsets": true,
  "can-read-varsets": true,
  "can-manage-public-providers": true,
  "can-create-provider": true,
  "can-manage-public-modules": true,
  "can-manage-custom-providers": true,
  "can-manage-run-tasks": true,
  "can-read-run-tasks": true,
  "can-create-project": true,
  "can-enable-stacks": false,
  "can-manage-org-public-providers": true,
  "can-manage-org-public-modules": true,
  "can-manage-assessments": true,
  "can-read-assessments": true,
  "can-view-explorer": true,
  "can-deploy-no-code-modules": true,
  "can-manage-no-code-modules": true,
  "can-create-change-requests": false,
  "can-manage-saved-views": true,
  "can-read-saved-views": true
}

Additional Information

• For more details on creating and managing tokens, see the API Tokens documentation.
• To download and install jq, visit the jq official website.