Create initial Terraform Enterprise admin user

After installing, you must create an admin user to use Terraform Enterprise. As an admin user, you can manage the Terraform Enterprise application and run workloads on your Terraform Enterprise Flexible Deployment Options installation.

1. Retrieve initial admin creation token (IACT)

To create your first Terraform Enterprise admin user, you must authenticate your request with the initial admin creation token (IACT). You can only use this token to create an admin user if there are no other users in the system.

The TFE_IACT_TIME_LIMIT setting determines the time limit in which you can retrieve the IACT token. When your application starts, it sets a time limit that controls how long the token is available for either the browser or API. By default, the time limit of the IACT token is 60 minutes.

This means that during the initial 60 minutes after the installation boots, a client can either use the API within the subnet list, or a browser to retrieve their IACT token. You can not access the IACT token after this time limit expires.

You can retrieve the initial admin creation token (IACT) in two ways: using the browser or directly from the container or pod.

With browser

Navigate to https://${TFE_HOSTNAME}/admin/retrieve-iact in your browser from a workstation within the subnet list. You can access your token on this webpage.

With container or pod

You can retrieve your IACT token directly from the Terraform Enterprise container or pod:

$ kubectl exec -it -n <TFE_NAMESPACE> <POD_NAME> -- tfectl admin token

$ docker exec <CONTAINER_NAME> tfectl admin token

$ podman exec -it <CONTAINER_NAME> tfectl admin token

$ nomad alloc exec -namespace=<TFE_NAMESPACE> -it -task <TFE_TASK_NAME> <ALLOCATION_ID> tfectl admin token

2. Create initial admin user

You can create the initial admin user in two ways: using the browser or directly from the container or pod.

With browser

Navigate to https://${TFE_HOSTNAME}/admin/account/new?token=${IACT_TOKEN} in your browser from a workstation within the subnet list. Follow the prompts to create the admin user.

With container or pod

You can create an initial admin user by making a POST request to your /admin/initial-admin-user endpoint. This endpoint requires your IACT token and a JSON document with the username, email address, and password for the admin user you want to create.

Query parameters

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

Request body

This POST endpoint requires a JSON object with the following properties as a request payload.

Response body

The POST endpoint returns a JSON object with the following properties.

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_HOSTNAME}/admin/initial-admin-user?token=${IACT_TOKEN}

Sample response

{
  "status": "created",
  "token": "aabbccdd.v1.atlas.ddeeffgghhiijjkkllmmnnooppqqrrssttuuvvxxyyzz"
}