• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Terraform
  • Install
  • Tutorials
    • About the Docs
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • CDK for Terraform
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
  • Registry(opens in new tab)
  • Try Cloud(opens in new tab)
  • Sign up
Terraform Home

Terraform Enterprise

Skip to main content
  • Terraform Enterprise
  • Operational Modes
    • Pre-Install Checklist
      • Automated Installation
      • Active/Active
      • Initial User Automation
      • Encryption Password
    • Uninstall
  • Migrating to Terraform Enterprise
  • Support

  • Terraform Cloud Agents

  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  • Terraform Registry
    (opens in new tab)
  1. Developer
  2. Terraform
  3. Terraform Enterprise
  4. Install and Configure
  5. Automated Install
  6. Initial User Automation
  • Terraform Enterprise
  • v202301-1
  • v202212-2
  • v202212-1
  • v202211-1
  • v202210-1
  • v202209-2
  • v202209-1
  • v202208-3
  • v202208-2
  • v202208-1
  • v202207-2
  • v202207-1
  • v202206-1

»Terraform Enterprise - Automating Initial User Creation

After Terraform Enterprise is installed, the initial admin user must then be created to begin using the product. Normally this user is created by opening the application from the installer dashboard. However, if further automation is desired, an API is available to create this user.

Initial Admin Creation Token (IACT)

To create the initial admin user via the API, the request must be authenticated with the Initial Admin Creation Token (IACT). This token can only be used to create the admin user when there are no users configured in the system. The IACT can be retrieved in several different ways.

Shell Command or Automated Deployment Script

After installation, run the following from a shell connected to your Terraform Enterprise instance:

replicated admin --tty=0 retrieve-iact

If you want to create the initial user in an automated deployment script, run a command that lets you capture the IACT. The following example command outputs the complete IACT with the carriage return character removed. The --tty=0 flag enables the command to run successfully in automation, such as cloud-init. Without this flag set, the command will return an empty string:

initial_token=$(replicated admin --tty=0 retrieve-iact | tr -d '\r')

The command outputs the complete IACT with the carriage return character removed, which facilitates use in automation.

Via API

The option iact_subnet_list can be set to a CIDR mask that will allow clients in that address range to query the retrieval API directly. This allows installers the ability to create the installation and then immediately request the IACT token without running a command on the installation machine.

NOTE: iact_subnet_list has no default value. If unset, no clients will be able to request the IACT token via the API.

The API will be relative to the installation, for example https://tfe.mycompany.com/admin/retrieve-iact, with /admin/retrieve-iact being the path that returns the token.

When this feature is used, it is governed by another setting: iact_subnet_time_limit. This is a time limit, measured from the installation starting, that controls external access to the IACT. By default this is set to 60 minutes, meaning that during the initial 60 minutes after the installation boots, the API can be used by a client within the subnet list. After that time, access is not allowed.

If a customer wishes to disable the time limit and allow access to the IACT forever, set the limit to unlimited.

Initial Admin Creation API

With the IACT in hand, the initial admin creation API can now be used. This API is available under the path /admin/initial-admin-user of your primary hostname. For instance, if your Terraform Enterprise instance was located at tfe.mycompany.com, the initial admin creation API would be https://tfe.mycompany.com/admin/initial-admin-user.

This API requires the IACT as well as a JSON document describing the username, email address, and password of the initial admin user.

Creating the Initial Admin User API

POST /admin/initial-admin-user

StatusResponseReason
200JSON documentSuccessfully created the user
404JSON error documentUnauthorized to perform action
422JSON error documentMalformed request body (missing attributes, wrong types, etc.)
500JSON error documentFailure during user creation

Query Parameters

These are standard URL query parameters; remember to percent-encode values if your tooling doesn't automatically encode URLs.

ParameterDescription
tokenRequired. The IACT token retrieved via API or command

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
usernamestringThe username to assign the new user.
emailstringThe email address of the new user.
passwordstringThe password of the new user.

Response Body

The POST endpoint will return a JSON object with the following properties.

Key pathTypeDescription
statusstringEither "created" or "error".
tokenstringIf status is "created", this contains a TFE user token for the new user.
errorstringIf status is "error", this contains the reason for the error.

Sample Payload

{
  "username": "admin",
  "email": "it@mycompany.com",
  "password": "thisisabadpassword"
}

Sample Request

curl \
  --header "Content-Type: application/json" \
  --request POST \
  --data @payload.json \
  https://tfe.company.com/admin/initial-admin-user?token=$(cat iact.txt)

Sample Response

{
  "status": "created",
  "token": "aabbccdd.v1.atlas.ddeeffgghhiijjkkllmmnnooppqqrrssttuuvvxxyyzz"
}
Edit this page on GitHub

On this page

  1. Terraform Enterprise - Automating Initial User Creation
  2. Initial Admin Creation Token (IACT)
  3. Initial Admin Creation API
  4. Creating the Initial Admin User API
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)