Why IaC for auth
Auth config drifts in ways application code doesn’t. An agent spun up by hand in a dashboard has no peer review, no version history, and no automated rollback. When the production incident happens and you need to know why an agent had write access to the deploy tool, “someone added it last Tuesday” is not an audit trail. Treating agents and permissions as Terraform resources fixes this. Every grant goes through a pull request. Every change is versioned in git. Destroying a staging environment tears down the access alongside the infrastructure, no orphaned tokens floating around.Installation
The provider requires Go 1.21 to build. It depends ongithub.com/glincker/theauth-go (the Go SDK in sdks/go) at v0.1.0, so building needs network access to that module or a local replace directive in sdks/terraform/go.mod.
1
From a checkout of this repository, build the binary:
2
Install into the local plugin cache:
3
Declare the provider in your Terraform configuration:
Provider setup
Base URL of your theAuth deployment, including the path where the adapter is mounted (for example
https://your-app.com/auth). Falls back to the THEAUTH_BASE_URL env var.Bearer token sent on every request. Falls back to the
THEAUTH_TOKEN env var. Marked sensitive.Authorization: Bearer <token>. How the server authenticates that token is up to your adapter configuration, theAuth does not mint a “provider token” for you.
Resources
theauth_agent
Manages an agent identity, the primary entity in theAuth. Destroying the resource revokes the agent (DELETE /agents/:id), it does not remove the row. owner_id and type force replacement when changed.
token attribute is computed on creation and marked sensitive. Expose it with an output block, then read it:
RFC 3339 expiry timestamp. Removing the argument does not clear an expiry that is already set.
token (sensitive), status, created_at, updated_at.
Permissions are evaluated in list order and only the first permission whose resource and actions match is used (see Permissions), so order the permission blocks from most to least specific.
Permission block arguments
Constraints block arguments
Regular expressions (not globs, despite the provider’s schema description). Every string argument must match every pattern.
timeWindow constraint.
theauth_permission
Grants a single permission to an existing agent from a separate module. If you control both the agent and all its permissions in one place, use inlinepermission blocks on theauth_agent instead.
PATCH /agents/:id) and identifies a permission by resource, so two theauth_permission resources with the same resource on one agent collide, and concurrent applies against the same agent can overwrite each other. It does not support terraform import. Do not combine it with inline permission blocks on the same agent: the next apply of the agent resource replaces the whole list.
theauth_api_key
Manages an API key for server-to-server requests. See the status warning at the top: the provider sendsPOST /api-keys with a scopes field, and the TypeScript server does not serve that route.
agents:read, agents:write, audit:read, delegation:read, delegation:write, organizations:read, organizations:write, admin.
The
key attribute is only populated immediately after creation. Read it with terraform output -raw ci_key and store it in your secret manager before the session ends.theauth_organization
Manages an organization for multi-tenant isolation. See the status warning at the top: the provider sendsPOST /organizations, and the TypeScript server does not serve that route.
slug is immutable after creation (lowercase alphanumeric with hyphens). Change it by deleting and recreating the organization. plan accepts free, pro, or enterprise; domains is an optional list. member_count, created_at, and updated_at are computed.
Data sources
theauth_agent
Reads an agent that was not created by this Terraform configuration.theauth_agents
Lists agents, optionally filtered.owner_id, status (active | revoked | expired), type (autonomous | delegated | service).
Import existing state
Resources provisioned outside Terraform can be brought under management:terraform plan. Terraform will show a diff for any attributes that differ from your configuration. Update the HCL to match, or let Terraform converge.
GitOps workflow
Manage theAuth configuration alongside your application infrastructure:Related
Agent identity
The agent lifecycle managed as Terraform resources.
Permissions
Resource-action permission model that Terraform permission resources declare.
Dashboard
Visual alternative to Terraform for one-off agent management.
Audit trail
Log of authorization decisions. Terraform changes are not audited by theAuth, so keep the Terraform history alongside it.