consul acl token create: Mint Consul Tokens in CI
consul acl token create issues a new ACL token tied to one or more policies or roles.
Pipelines should run with a scoped token, not the bootstrap token. acl token create mints one bound to exactly the policies a job needs.
What it does
consul acl token create creates a token and links it to policies (by name or id), roles, or service identities. It returns the AccessorID and the SecretID; the SecretID is the value you put in CONSUL_HTTP_TOKEN. Requires acl:write, normally the bootstrap or a management token.
Common usage
consul acl token create \
-description="ci-deploy" \
-policy-name=deploy-policy
# bind a service identity instead of a policy
consul acl token create \
-description="web sidecar" \
-service-identity="web:dc1"Options
| Flag | What it does |
|---|---|
| -policy-name <name> | Attach a policy by name (repeatable) |
| -policy-id <id> | Attach a policy by id |
| -role-name <name> | Attach a role by name |
| -service-identity <svc:dc> | Grant a synthetic service identity |
| -description <text> | Human-readable token description |
| -format json | Output token details as JSON for scripting |
In CI
Use -format json and parse out the SecretID to export as CONSUL_HTTP_TOKEN for later steps. Give the token only the policies the job needs (least privilege), and prefer short-lived tokens you delete in a teardown step.
Common errors in CI
"Failed to create new token: Unexpected response code: 401 (ACL support disabled)" means ACLs are off in the agent config. "Unexpected response code: 403 (Permission denied)" means the calling token lacks acl:write. "Invalid Policy: ... Cannot find policy" means -policy-name references a policy that does not exist yet.