Skip to main content
Status: experimental, built from source only. The provider lives in this repository at sdks/terraform (version 0.1.0, Terraform SDK v2). It is not published to the Terraform Registry, so the theauth/theauth source only resolves through the local plugin directory or a dev override as shown below.Only theauth_agent, theauth_permission, and the two theauth_agent data sources are backed by REST routes that the TypeScript server ships (/agents, /agents/:id, /agents/:id/rotate in the framework adapters, via the Go SDK in sdks/go). theauth_api_key calls /api-keys with a scopes body, and theauth_organization calls /organizations with slug, plan, and domains. The server has no such routes: the API key plugin serves /auth/api-keys (user session auth, body field permissions) and the organization plugin serves /auth/org/*. Treat those two resources as unsupported until the server and provider agree. All resource and attribute names below are taken from the provider schema in sdks/terraform.

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 on github.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

Both arguments can be set via environment variables, which is preferred in CI:
string
required
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.
string
required
Bearer token sent on every request. Falls back to the THEAUTH_TOKEN env var. Marked sensitive.
Both are required; the provider errors at configure time if neither the argument nor the env var is set. The token is sent as 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.
The token attribute is computed on creation and marked sensitive. Expose it with an output block, then read it:
The token is also stored in Terraform state, so protect the state backend.
The raw token is only returned once, at creation time. theAuth does not store it in recoverable form, and the provider leaves token empty for imported agents. If you lose it, rotate the agent’s token with POST /agents/:id/rotate (the provider has no rotation attribute, so the new token will not appear in Terraform state).
string
required
ID of the user who owns this agent.
string
required
Human-readable name.
"autonomous" | "delegated" | "service"
required
Agent type: autonomous, delegated, or service.
block[]
One or more permission grant blocks.
string
RFC 3339 expiry timestamp. Removing the argument does not clear an expiry that is already set.
Computed attributes: 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
string
required
Resource pattern, e.g. mcp:github:* or mcp:deploy:production.
string[]
required
Allowed actions, e.g. [“read”] or [“execute”].
block
Optional block limiting usage.
Constraints block arguments
bool
default:"false"
Require human approval before the action executes.
number
Rate limit: maximum calls allowed per hour.
string[]
Regular expressions (not globs, despite the provider’s schema description). Every string argument must match every pattern.
string[]
IPv4 addresses or CIDR blocks from which this permission may be used.
The provider does not expose the 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 inline permission blocks on theauth_agent instead.
string
required
ID of the target agent.
string
required
Resource pattern.
string[]
required
Allowed actions.
bool
default:"false"
Require human approval.
number
Rate limit per hour.
string[]
Regular expressions for argument values (see above).
string[]
IPv4 addresses or CIDR blocks allowed to exercise the permission.
This resource edits the agent’s permission list (read, modify, 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 sends POST /api-keys with a scopes field, and the TypeScript server does not serve that route.
Valid scopes: 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 sends POST /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.
Filter arguments: owner_id, status (active | revoked | expired), type (autonomous | delegated | service).

Import existing state

Resources provisioned outside Terraform can be brought under management:
After importing, run terraform plan. Terraform will show a diff for any attributes that differ from your configuration. Update the HCL to match, or let Terraform converge.
Importing an API key restores the ID and metadata but not the raw key value, that was only available at creation time.

GitOps workflow

Manage theAuth configuration alongside your application infrastructure:
A minimal GitHub Actions workflow:
Every permission change ships as a pull request diff. The plan output shows what will change before it is applied, and the apply only runs on merge to main. The same controls you use for code changes (required reviewers, branch protection, signed commits) then apply to auth config changes. Note that the plan file and state contain agent tokens, so restrict access to both.

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.
Last modified on October 7, 2026