State-only tokens

A pipeline that doesn't run on Firstlume yet (your CI, GitLab CI and so on) can use Firstlume's state with a state token from the stack. It gains locks and versions before its runs migrate.

Create a token

curl -X POST -H "Authorization: Bearer $ADMIN" "$API/api/v1/orgs/$ORG/stacks/$STACK/state/tokens" \
  -d '{"name": "ci", "write": true}'   # "expires_at" is optional

The token appears only in this response. A token is valid for its own stack only.

GET    .../state/tokens        # lists tokens, with last use
DELETE .../state/tokens/{id}   # revokes a token

Permissions

• Read and write ("write": true): reads, locks and writes. Each version it writes carries the token's name. A lock taken by a token doesn't release itself: only Terraform's own UNLOCK releases it.
• Read only: only reads. The plan runs with -lock=false, so a read-only token never holds a unit.

In the pipeline

With the root.hcl from State backend:

export FIRSTLUME_STATE_URL=https://firstlume.example.com/state/v1/stacks/$STACK
export TF_HTTP_USERNAME=firstlume TF_HTTP_PASSWORD=$FIRSTLUME_STATE_TOKEN
terragrunt run --all -- plan -lock=false      # read token
terragrunt run --all -- apply                 # write token

To move a pipeline that keeps its state in a bundle, see Migrate a pipeline.