Documentation · API reference

API tokens

User and organisation tokens for the Terraform API: where they come from, how to give one to the CLI, and how to take one back.

Tokens for the Terraform API are issued and revoked in the dashboard, on Settings. They are not issued by the API host: tf.runners.io serves machine paths only and has no interface to sign in to, which is deliberate.

terraform login tf.runners.io therefore does not work. Discovery advertises the endpoint, but the browser step of that flow is on a path the host does not serve.

A user token carries the permissions of the person it belongs to. Connecting the Terraform engine issues one and shows it once — it is not stored anywhere we can read it. If you lose it, revoke it, and use an organisation token instead.

Give it to the CLI as an environment variable:

export TF_TOKEN_tf_runners_io=<your token>

That name is Terraform's own convention: TF_TOKEN_ followed by the hostname with dots replaced by underscores. The CLI picks it up with no further configuration. A credentials file works too if you prefer one, and the CLI documents its format.

Your tokens are listed under Settings → Your Terraform API tokens, with the date each was created and a button to revoke it. A revoked token stops working immediately.

The list is yours, not the organisation's. A colleague's tokens are not shown to you and yours are not shown to them. An administrator who needs to cut somebody off removes them from the organisation, which stops their tokens seeing anything — that is a different and more appropriate power than reading the list of credentials another person holds.

An organisation can also hold a single token of its own, for automation that should not belong to a particular person — a pipeline that outlives whoever set it up. It is under Settings → The organisation's token. Only an owner or an admin can issue or revoke it, and issuing a new one replaces the old.

It is equivalent to an HCP Terraform organization token and carries the permissions documented there.

Use a user token for your own workstation. Use the organisation token for shared automation, and revoke it deliberately when the automation is retired.

Neither is the credential your workflows use — a CI job on our runners authenticates through GitHub's own machinery and needs nothing from this page.