​
API Reference

OpenTaco exposes multiple HTTP API surfaces for different use cases:

​
Management API (prefix /v1)

Auth
  • All endpoints under /v1 require Authorization: Bearer <access> unless the service is started with -auth-disable.
  • Acquire tokens via the taco login CLI and see identity via GET /v1/auth/me.
Units
  • POST /v1/units — create
  • GET /v1/units?prefix=<string> — list
  • GET /v1/units/{id} — get metadata
  • DELETE /v1/units/{id} — delete
  • GET /v1/units/{id}/download — download tfstate
  • POST /v1/units/{id}/upload[?if_locked_by=<uuid>] — upload tfstate
  • POST /v1/units/{id}/lock — acquire lock
  • DELETE /v1/units/{id}/unlock — release lock
  • GET /v1/units/{id}/status — dependency-driven status
    • Response:
    {
  "unit_id": "org/app/B",
  "status": "red|yellow|green",
  "incoming": [
    {
      "edge_id": "...",
      "from_unit_id": "org/app/A",
      "from_output": "db_url",
      "status": "pending|ok|unknown",
      "in_digest": "...",
      "out_digest": "...",
      "last_in_at": "...",
      "last_out_at": "..."
    }
  ],
  "summary": { "incoming_ok": 0, "incoming_pending": 1, "incoming_unknown": 0 }
}
    • Semantics:
      • red: any incoming pending
      • yellow: no incoming pending, but some upstream is red
      • green: neither red nor yellow
Versions
  • GET /v1/units/{id}/versions — list all versions with timestamps and hashes
  • POST /v1/units/{id}/restore — restore to a specific version by timestamp
Notes
  • IDs use natural paths like myapp/prod; clients may encode as myapp__prod for single-segment routes.
  • Upload respects if_locked_by to avoid overwriting when held by a different lock.
Auth endpoints
  • GET /v1/auth/config — Server OIDC config (issuer, client_id, optional endpoints, redirect URIs).
  • POST /v1/auth/exchange — Exchange OIDC ID token for OpenTaco access/refresh tokens.
  • POST /v1/auth/token — Refresh to new access (rotates refresh).
  • POST /v1/auth/issue-s3-creds — Issue stateless STS credentials (requires Bearer).
  • GET /v1/auth/me — Echo subject/roles/groups from Bearer.
  • GET /oidc/jwks.json — JWKS with current signing key.

​
Terraform Cloud API (prefix /tfe/api/v2)

OpenTaco implements the Terraform Cloud API v2 for terraform cloud backend compatibility.

​
Authentication & Discovery

  • GET /.well-known/terraform.json — Service discovery (login endpoints, API version)
  • GET /oauth/authorization — OAuth2 authorization endpoint (PKCE)
  • POST /oauth/token — OAuth2 token exchange

​
Organizations & Workspaces

  • GET /tfe/api/v2/organizations/{org}/entitlement-set — Organization entitlements
  • GET /tfe/api/v2/account/details — User account details
  • GET /tfe/api/v2/organizations/{org}/workspaces/{name} — Get workspace by name

​
Workspace Operations

  • POST /tfe/api/v2/workspaces/{id}/actions/lock — Lock workspace
  • POST /tfe/api/v2/workspaces/{id}/actions/unlock — Unlock workspace
  • POST /tfe/api/v2/workspaces/{id}/actions/force-unlock — Force unlock workspace

​
State Management

  • GET /tfe/api/v2/workspaces/{id}/current-state-version — Get current state version
  • POST /tfe/api/v2/workspaces/{id}/state-versions — Create new state version
  • GET /tfe/api/v2/state-versions/{id} — Get state version details
  • GET /tfe/api/v2/state-versions/{id}/download — Download state content

​
Upload Endpoints (Auth-exempt)

  • PUT /tfe/api/v2/state-versions/{id}/upload — Upload state content
  • PUT /tfe/api/v2/state-versions/{id}/json-upload — Upload JSON state outputs
Note: Upload endpoints are exempt from auth middleware since Terraform doesn’t send headers during uploads. Security is maintained through upload URL validation, lock ownership checks, and RBAC permissions in handlers.

​
Workspace ID Mapping

OpenTaco maps Terraform Cloud workspace IDs to unit IDs:
  • Workspace ID ws-myworkspace becomes unit ID myworkspace
  • Direct workspace names are used as-is for unit IDs
  • RBAC permissions are checked against the converted unit ID